|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <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 |
|
13 and file caching features for file systems implementations.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-450D57A3-928B-5389-B941-595DB20A7CEA"><title>Enabling |
|
15 fair scheduling</title><p>The <codeph>MExtendedFileInterface</codeph> API enables fair scheduling. The FAT, FAT32 and LFFS file systems |
|
16 support <codeph>MExtendedFileInterface</codeph>, this API allows requests |
|
17 to be split into one or more segments with the <codeph>aOffset</codeph> parameter. Support has been built in for large files by changing |
|
18 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 |
|
19 fair scheduling, the file system mounted on a particular drive must |
|
20 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 |
|
21 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 |
|
22 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 |
|
23 { |
|
24 public: |
|
25 virtual void ReadL(TInt64 aPos, TInt& aLength, TDes8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0; |
|
26 virtual void WriteL(TInt64 aPos, TInt& aLength, const TDesC8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0; |
|
27 virtual void SetSizeL(TInt64 aSize) = 0; |
|
28 };</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 |
|
29 as in the following example: </p><codeblock id="GUID-714AB83B-0A24-5E81-92B8-CB425002B426" xml:space="preserve">TInt CFatFileCB::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* aInput) |
|
30 { |
|
31 switch(aInterfaceId) |
|
32 { |
|
33 case EExtendedFileInterface: |
|
34 ((CFileCB::MExtendedFileInterface*&) aInterface) = this; |
|
35 return KErrNone; |
|
36 |
|
37 //etc. |
|
38 |
|
39 default: |
|
40 return CFileCB::GetInterface(aInterfaceId, aInterface, aInput); |
|
41 } |
|
42 }</codeblock> </section> |
|
43 <section id="GUID-719C7E0C-790B-5C61-9EA8-E2687397340F"><title>Enabling |
|
44 read and write caching</title><p>To enable caching, the file system |
|
45 must support reads and writes to local buffers, which are buffers |
|
46 created and owned by the file server itself rather by a client of |
|
47 the file server. </p><p>The local media subsystem already supports |
|
48 local messages, but the file system and any file system extensions |
|
49 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 |
|
50 mounted on a particular drive fully support local buffers before it |
|
51 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 |
|
52 and passes the request on to the first proxy drive, as in the following |
|
53 example: </p><codeblock id="GUID-969BBBAE-5C1F-5032-831D-3C17E58285AE" xml:space="preserve">TInt CFatMountCB::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* /*aInput*/) |
|
54 { |
|
55 TInt r= KErrNone; |
|
56 switch(aInterfaceId) |
|
57 { |
|
58 // file caching supported, so pass query on to first proxy drive |
|
59 case CMountCB::ELocalBufferSupport: |
|
60 r = LocalDrive()->LocalBufferSupport(); |
|
61 break; |
|
62 default: |
|
63 r=KErrNotSupported; |
|
64 } |
|
65 return r; |
|
66 }</codeblock> <p>If no file system extensions are loaded, then |
|
67 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 |
|
68 buffers. </p> <p>If there are any file system extensions, they must |
|
69 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, |
|
70 as in the following example: </p><codeblock id="GUID-67D3FAA1-9FC3-5653-B21D-73BC13AA36AE" xml:space="preserve">TInt CBitExtProxyDrive::GetInterface(TInt aInterfaceId, TAny*& aInterface, TAny* aInput) |
|
71 { |
|
72 switch(aInterfaceId) |
|
73 { |
|
74 // file caching supported, so pass query on to next proxy drive |
|
75 case ELocalBufferSupport: |
|
76 return CBaseExtProxyDrive::LocalBufferSupport(); |
|
77 |
|
78 default: |
|
79 return CBaseExtProxyDrive::GetInterface(aInterfaceId, aInterface, aInput); |
|
80 } |
|
81 }</codeblock> </section> |
|
82 <section id="GUID-020006B9-1A1E-523B-9CFA-927CDE5D5058"><title>Configuring |
|
83 caching</title><p>The global and drive-specific cache property defaults |
|
84 are defined in <filepath>f32\sfile\sf_file_cache_defs.h</filepath>. They may be overridden for a particular drive by appropriate entries |
|
85 in the Base Starter component's <filepath>ESTART.TXT</filepath> configuration |
|
86 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 |
|
87 D: 1 ELOCAL FAT 0 FS_SCANDRIVE # MMC (textshell) |
|
88 I: 2 ELOCAL FAT 0 FS_FORMAT_CORRUPT # NAND - USER DATA |
|
89 K: 8 ELFFS LFFS 0 FS_FORMAT_CORRUPT # LFFS |
|
90 |
|
91 [DriveD] |
|
92 FileCacheSize 256 |
|
93 FairSchedulingLen 128 |
|
94 FileCacheRead ON |
|
95 FileCacheReadAhead ON |
|
96 FileCacheWrite ON |
|
97 ClosedFileKeepAliveTime 3000 |
|
98 DirtyDataFlushTime 3000 |
|
99 FileCacheReadAsync ON |
|
100 |
|
101 [DriveI] |
|
102 FileCacheWrite ENABLED |
|
103 |
|
104 [DriveK] |
|
105 FileCacheWrite ENABLED |
|
106 |
|
107 [FileCache] |
|
108 GlobalCacheEnabled ON |
|
109 GlobalCacheSize 32768 |
|
110 GlobalCacheMaxLockedSize 1024 |
|
111 LowMemoryThreshold 10</codeblock> <p>In this example, write caching |
|
112 is enabled on drives I and K and has been turned on by default on |
|
113 drive D.</p><note>Most of the properties in the example are set to |
|
114 their default values: the definitions are redundant but are shown |
|
115 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 |
|
116 cache settings</b> </p><p>The following table holds the global caching |
|
117 properties: </p><table id="GUID-4CBAD2A4-52DE-5BA1-98CC-0B1F6BFC54E1"> |
|
118 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/> |
|
119 <colspec colname="col2"/><colspec colname="col3"/> |
|
120 <tbody> |
|
121 <row> |
|
122 <entry><p> <b>Property</b> </p> </entry> |
|
123 <entry><p> <b>Type</b> </p> </entry> |
|
124 <entry><p> <b>Comments</b> </p> </entry> |
|
125 <entry><p> <b>Default value</b> </p> </entry> |
|
126 </row> |
|
127 <row> |
|
128 <entry><p> <xref href="GUID-91B81C0D-72F9-3226-BEEF-2E8153104102.dita"><apiname>GlobalCacheEnabled</apiname></xref> </p></entry> |
|
129 <entry><p>boolean </p></entry> |
|
130 <entry><p>on or off</p></entry> |
|
131 <entry><p>on</p></entry> |
|
132 </row> |
|
133 <row> |
|
134 <entry><p> <xref href="GUID-BAC3ED91-7A3A-3255-B22E-6B6C0CB266E0.dita"><apiname>GlobalCacheSize</apiname></xref> </p></entry> |
|
135 <entry><p>integer </p> </entry> |
|
136 <entry><p>Size of disconnected chunk shared by all files in kilobytes.</p></entry> |
|
137 <entry><p>32768K (32MB) </p> </entry> |
|
138 </row> |
|
139 <row> |
|
140 <entry><p> <xref href="GUID-BEE48B25-B374-3348-B97C-BA2D634E0330.dita"><apiname>GlobalCacheMaxLockedSize</apiname></xref> </p></entry> |
|
141 <entry><p>integer </p> </entry> |
|
142 <entry><p>Maximum amount of locked RAM for all files in kilobytes.</p></entry> |
|
143 <entry><p>1024K (1 MB) </p> </entry> |
|
144 </row> |
|
145 <row> |
|
146 <entry><p> <xref href="GUID-36596759-4ABC-3F8E-A09E-97464094A58A.dita"><apiname>LowMemoryThreshold</apiname></xref> </p></entry> |
|
147 <entry><p>integer </p></entry> |
|
148 <entry><p>Low memory threshold expressed as a percentage of total |
|
149 RAM. If the amount of RAM drops below this value, attempts to allocate |
|
150 memory for file caching fails.</p></entry> |
|
151 <entry><p>10% </p> </entry> |
|
152 </row> |
|
153 </tbody> |
|
154 </tgroup> |
|
155 </table> <p id="GUID-E7F45784-14F2-505C-B21C-0A8010B0B232"><b>File |
|
156 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> |
|
157 <li id="GUID-71396310-22E1-564A-A094-3EED4721688D"><p> <codeph>OFF</codeph> - file caching is permanently off and cannot be turned on.</p> </li> |
|
158 <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 |
|
159 file open mode, such as <xref href="GUID-4310DC20-300C-3FEB-B1A5-DBA37D5FC940.dita"><apiname>EFileReadBuffered</apiname></xref> </p> </li> |
|
160 <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 |
|
161 file open mode, such as <xref href="GUID-449D6D3A-3F00-35F6-BDFB-DF957F98CA8B.dita"><apiname>EFileReadDirectIO</apiname></xref>. </p> </li> |
|
162 </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 |
|
163 results in read ahead requests being issued before completing a client |
|
164 read request. However, if <codeph>FileCacheReadAsync</codeph> is OFF, |
|
165 then media driver reads on this drive are synchronous. So, issuing |
|
166 a read ahead is likely to block any client thread that is normally |
|
167 running at lower priority than the media driver's thread. In this |
|
168 case read ahead requests only happen during periods of inactivity |
|
169 to improve latency. </p><table id="GUID-B022918E-9335-5D44-B029-D48B36E45937"> |
|
170 <tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/> |
|
171 <colspec colname="col2"/><colspec colname="col3"/> |
|
172 <tbody> |
|
173 <row> |
|
174 <entry><p> <b>Property</b> </p> </entry> |
|
175 <entry><p> <b>Type</b> </p> </entry> |
|
176 <entry><p> <b>Comments</b> </p> </entry> |
|
177 <entry><p> <b>Default value</b> </p> </entry> |
|
178 </row> |
|
179 <row> |
|
180 <entry><p> <xref href="GUID-3B777E89-8E4C-3540-958F-C621741895C8.dita"><apiname>FileCacheSize</apiname></xref> </p> </entry> |
|
181 <entry><p>integer </p> </entry> |
|
182 <entry><p>Maximum amount of locked or unlocked RAM per file.</p></entry> |
|
183 <entry><p>128K </p> </entry> |
|
184 </row> |
|
185 <row> |
|
186 <entry><p> <xref href="GUID-23E2F01D-BD7B-39D3-B7B2-F23E20D273C5.dita"><apiname>FairSchedulingLen</apiname></xref> </p> </entry> |
|
187 <entry><p>integer </p> </entry> |
|
188 <entry><p>Read & write requests greater than this length are split |
|
189 up into 2 or more requests.</p></entry> |
|
190 <entry><p>128K </p> </entry> |
|
191 </row> |
|
192 <row> |
|
193 <entry><p> <xref href="GUID-9278B920-FFEF-3710-8080-B33D028B7A12.dita"><apiname>FileCacheRead</apiname></xref> </p></entry> |
|
194 <entry><p>string </p></entry> |
|
195 <entry><p>OFF, ENABLED or ON.</p></entry> |
|
196 <entry><p>ENABLED </p></entry> |
|
197 </row> |
|
198 <row> |
|
199 <entry><p> <xref href="GUID-33E32FCF-9E02-3254-A9DA-3A6D0B1A52B5.dita"><apiname>FileCacheReadAhead</apiname></xref> </p></entry> |
|
200 <entry><p>string </p></entry> |
|
201 <entry><p>OFF, ENABLED or ON.</p></entry> |
|
202 <entry><p>ON </p></entry> |
|
203 </row> |
|
204 <row> |
|
205 <entry><p> <xref href="GUID-C869ED9F-7F9D-33BC-A1C2-5E21B50A6BFC.dita"><apiname>FileCacheWrite</apiname></xref> </p></entry> |
|
206 <entry><p>string </p></entry> |
|
207 <entry><p>OFF, ENABLED or ON.</p></entry> |
|
208 <entry><p>ENABLED </p></entry> |
|
209 </row> |
|
210 <row> |
|
211 <entry><p> <xref href="GUID-7F7B7C49-5F60-3B10-A241-98306795A768.dita"><apiname>FileCacheReadAsync</apiname></xref> </p> </entry> |
|
212 <entry><p>boolean </p> </entry> |
|
213 <entry><p>ON or OFF. If set, media driver reads on this drive are |
|
214 asynchronous.</p></entry> |
|
215 <entry><p>OFF </p> </entry> |
|
216 </row> |
|
217 <row> |
|
218 <entry><p> <xref href="GUID-A91BE0A1-A79D-3828-9E86-7850839BBFE9.dita"><apiname>ClosedFileKeepAliveTime</apiname></xref> </p> </entry> |
|
219 <entry><p>integer </p> </entry> |
|
220 <entry><p>Time after which a file is removed from the closed file |
|
221 queue, in milliseconds. </p></entry> |
|
222 <entry><p>3000ms (3 secs) </p> </entry> |
|
223 </row> |
|
224 <row> |
|
225 <entry><p> <xref href="GUID-78907F25-9D0F-3B76-BDB0-514FC22CAECA.dita"><apiname>DirtyDataFlushTime</apiname></xref> </p> </entry> |
|
226 <entry><p>integer </p> </entry> |
|
227 <entry><p>Time after which a file containing dirty data is flushed, |
|
228 in milliseconds.</p></entry> |
|
229 <entry><p>3000ms (3 secs) </p> </entry> |
|
230 </row> |
|
231 </tbody> |
|
232 </tgroup> |
|
233 </table> </section> |
|
234 </conbody><related-links> |
|
235 <link href="GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita"><linktext>Fair |
|
236 Scheduling and File Caching Background</linktext></link> |
|
237 </related-links></concept> |