<?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-0B240B41-652F-586A-915E-3D67BFEB8AE6" xml:lang="en"><title> F32 Performance
Test Suite</title><shortdesc>The F32 Performance test suite provides performance tests for the
most frequently used public APIs in the <codeph>RFile</codeph> and <codeph>RFs</codeph> classes.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-7B1608D1-4699-5255-B1F5-CADF53C14006"><title>Test Suite
Overview</title> <p> This test suite provides an indication of the overall
performance characteristics of the file server. </p> <p>The following APIs
are tested: </p> <p> <b> RFile APIs:</b>  </p> <codeblock id="GUID-F238955F-34F2-5FB7-9649-5001F5BE68EF" xml:space="preserve">IMPORT_C TInt Read(TDes8 &amp;aDes, TInt aLength) const;
IMPORT_C TInt Read(TInt aPos, TDes8 &amp;aDes, TInt aLength) const;
IMPORT_C TInt Write(TDes8 &amp;aDes, TInt aLength) const;
IMPORT_C TInt Write(TInt aPos, TDes8 &amp;aDes, TInt aLength) const;
IMPORT_C TInt Seek(TSeek aMode, TInt aPos) const;
</codeblock> <p> <b> RFs APIs: </b>  </p> <codeblock id="GUID-4F8C5908-15CA-57D7-B61A-3E1FFEFA266A" xml:space="preserve">IMPORT_C TInt Entry(const TDesC &amp;aName, TEntry &amp;anEntry) const;</codeblock> </section>
<section id="GUID-6D219777-ADAA-4702-AFCC-FAB3822476D6"><title>Test approach</title> <p>The suite benchmarks the performance
of the APIs for each call is then calculated. by recording the time taken
for a given number calls to each API to complete. The average time taken </p> <p>The
suite consists of six test scripts: Three for RFile and three for RFs. </p> <p>The
three tests are described as small, medium and large according to the number
of times that a API is called. Small indicates that the API will be called
100 times, medium 500 times and large 1000 times. </p> </section>
<section id="GUID-412FEEB7-868E-4E99-AD7E-134909561AB3"><title>Coverage Omissions</title> <p>Not all the public Base F32
APIs are tested by the test suite. The scope is limited to the most frequently
used APIs of RFs and RFile (see <xref href="GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita#GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6/GUID-7B1608D1-4699-5255-B1F5-CADF53C14006">Test
Suite Overview</xref> for details). </p> </section>
<section id="GUID-9A967A34-A634-4A01-954A-905B8EEBE37A"><title>Test Suite Details</title> <p><b>Test
Script Source Tree Location</b> </p> <p>Descriptions of the test cases that
is test scripts can be found at the following location: </p> <ul>
<li id="GUID-FB05188F-3E94-55DB-B7C7-D8359F723A6B"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfile-performance-large.script</filepath> </p> </li>
<li id="GUID-A0CC9A69-682D-58EC-8A5A-663BCFF90F4D"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfile-performance-medium.script</filepath> </p> </li>
<li id="GUID-2D648B37-5515-5167-84B6-CF02BB440074"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfile-performance-small.script</filepath> </p> </li>
<li id="GUID-672D1C70-E309-55CC-985F-78F552EAAC09"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfs-performance-large.script</filepath> </p> </li>
<li id="GUID-5657F030-CE25-5FD2-9809-3B23779D9103"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfs-performance-medium.script</filepath> </p> </li>
<li id="GUID-CDB7F091-D015-5DF9-A928-65E859057E3A"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\scripts\pbase-f32-rfs-performance-small.script</filepath> </p> </li>
</ul> <p><b>Test
Script EPOC tree Location</b> </p> <p>When the tests are built for emulator
or hardware (<codeph>WINSCW</codeph> or <codeph>ARMV5</codeph>), the scripts
are exported into the following location in the epoc tree: </p> <p> <filepath>%EPOCROOT%\epoc32\data\Z\base\performance\f32\t_perf\</filepath>  </p> <p><b>Test
Script Build Location</b> </p> <p>When the tests are built, the scripts are
built into the following location: </p> <p> <filepath>%EPOCROOT%\epoc32\release\&lt;winscw|armv5&gt;\&lt;udeb|urel&gt;\Z\base\performance\f32\t_perf\</filepath> </p> <note><p> When the tests are built to be executed on hardware the files
are built into the z: drive of the ROM. </p></note> <p><b>Test Data Source Tree Location</b> </p> <p>The test suite contains following
test data files: </p> <ul>
<li id="GUID-94ABEC01-1869-5CED-B899-A2924B582C4B"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfile-performance-large.ini</filepath> </p> </li>
<li id="GUID-1C377989-B6A7-5968-89B6-1C1C156D25F0"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfile-performance-medium.ini</filepath> </p> </li>
<li id="GUID-F29B2192-F68E-5FC9-87BF-47E20AE0959E"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfile-performance-small.ini</filepath> </p> </li>
<li id="GUID-4D7E58C6-D2E8-54F2-B445-EC97AF087A76"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfile-performance-utils.ini</filepath> </p> </li>
<li id="GUID-897DB828-95AD-5E55-8DDE-A66E4E8FB20D"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfs-performance-large.ini</filepath> </p> </li>
<li id="GUID-166661ED-8AB9-5188-AFD0-09AAD7329AB9"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfs-performance-medium.ini</filepath> </p> </li>
<li id="GUID-FC9D6EBD-A2FB-5EE8-99C5-24B25FE21AF0"><p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\pbase-f32-rfs-performance-small.ini</filepath> </p> </li>
</ul> <p>The global environment file located at: </p> <p> <filepath>...\baseapitest\basesvs\performance\f32\t_perf\testdata\&lt;platform&gt;\base_perf_f32_env.ini</filepath> </p> <p>where <codeph>&lt;platform&gt;</codeph> is either <codeph>WINSCW</codeph> or <codeph>ARMV5</codeph>. </p> <p><b>Test Data Files EPOC Tree Location</b> </p> <p>When the tests are built
for emulator or hardware (winscw/armv5), the data files are exported into
the following location in the epoc tree: </p> <p> <filepath>%EPOCROOT%\epoc32\data\Z\base\performance\f32\t_perf\</filepath>  </p> <p><b>Test Data Files Emulator Location</b> </p> <p>When the tests are built,
the test data files are built into the following location: </p> <p> <filepath>%EPOCROOT%\epoc32\release\winscw\&lt;udeb/urel&gt;\Z\base\performance\f32\t_perf\</filepath> </p> <p> <b>Note:</b> When the tests are built to be executed on hardware
the files are built into the z: drive of the ROM. </p> <p><b>Test .driver File</b> </p> <p>The <filepath>base.driver</filepath> file
found in <filepath>…\baseapitest\basesvs\testsuites\base</filepath> \ is used
by the test driver to construct the test suite tree structure and export all
the appropriate files to the correct location in the epoc32 tree and on the
device. </p> <p>When the tests are built, the <filepath>.driver</filepath> file
can be found in the following location: </p> <p> <filepath>%EPOCROOT%\epoc32\testdriver\testproduct\..</filepath>  </p> <p id="GUID-4FC8CBD4-02FE-566E-B739-C6EB8DDD6C48"><b>TCS File Source Location</b> </p> <p>The <filepath>.tcs</filepath> file
can be found in the following location: </p> <p> <filepath>...\baseapitest\basesvs\config\t_base.tcs</filepath>  </p> <p><b>TCS File Build Location</b> </p> <p>When the tests are built, the <filepath>.tcs</filepath> file
is generated into the following location: </p> <p> <filepath>%EPOCROOT%\epoc32\release\&lt;winscw|armv5&gt;\&lt;udeb|urel&gt;\Z\base\performance\f32\t_perf\</filepath> </p> <note><p> When the tests are built to be executed on hardware, the
files are built into the z: drive of the ROM. </p></note> <p id="GUID-03EBC248-B2FE-5DFF-941A-A386348596B4"><b>Test configuration</b> </p> <p>Tests
can be configured separately using the environment configuration file <filepath>base_perf_f32_env.ini</filepath>.
This file contains configurable parameters which you can modify to execute
with different test data. </p> <p>For example : </p> <ul>
<li id="GUID-9810291D-1B6B-5607-AED2-D4DADC22A478"><p>the name of the drive
on which to create the test directory structure </p> </li>
<li id="GUID-0F0C64EC-DDE9-5D20-B8F8-D40BA38DC52E"><p>the name of the file(s)
to create </p> </li>
<li id="GUID-01EFEE40-F510-5EF1-945F-665FA18B3DBF"><p>the size of the file(s)
to create </p> </li>
<li id="GUID-D172D475-8AF4-50FB-9AC5-CC6A270B5198"><p>the number of files
to create in each directory </p> </li>
<li id="GUID-5A700E65-935C-5BCC-98E4-69C48E0DE5DC"><p>the name of each directory
to create in the directory structure </p> </li>
</ul> <p>The following parameters are within the default section of the <filepath>base_perf_f32_env.ini </filepath> configuration
file: </p> <ul>
<li id="GUID-41272491-7D9D-5366-9A03-CD234D8DB390"><p>driveName </p> </li>
<li id="GUID-9EDB965E-59C6-53C6-8109-CD8F0CCA6F29"><p>fileBaseName </p> </li>
<li id="GUID-05ACC1ED-92A4-598E-99C9-D7690D9AD877"><p>fileSize </p> </li>
<li id="GUID-5D98C4C9-26A4-5397-BF09-EAFC649BE874"><p>numOfFiles </p> </li>
<li id="GUID-45570A4D-2AD9-5230-8777-142D65D0F882"><p>subDirName </p> </li>
</ul> <p>You can also modify the values of these parameters, and other parameters
available in the <filepath>base_perf_f32_env.ini</filepath> configuration
file. For more information about the parameters available in the <filepath>base_perf_f32_env.ini</filepath> configuration
file, see the <xref href="GUID-2988AB7C-F8BB-5917-BB22-A57C0CC56C73.dita">Configuring
the base_perf_f32_env.ini file</xref> section. </p> <p> <note>As the configuration
file <filepath>base_perf_f32_env.ini</filepath> is used by all RFile tests
and RFs tests, it is important to analyse all test scenarios before modifying
this configuration file.</note>  </p> <p>For more information about the details
that can be manipulated for each test scenario, see the <xref href="GUID-2988AB7C-F8BB-5917-BB22-A57C0CC56C73.dita">Configuring
the base_perf_f32_env.ini file</xref> section. </p> </section>
<section id="GUID-CF25C29E-0740-413A-9DA0-035CC6CBA4CD"><title>Test environment and execution</title> <p><b>Device
Setup</b> </p> <p>None </p> <p><b>Test
Execution</b> </p> <p>The following two different ROM configurations can be
used to run these tests on the target platform: </p> <ul>
<li id="GUID-5A7672CA-19E0-509D-B201-38BCA8C664B7"><p>NAND configuration ROM </p> </li>
<li id="GUID-F6AD705B-0934-59F2-8961-BF522E1463AA"><p>NOR configuration ROM </p> </li>
</ul> <p><note> Both ROMS described in the following sections are <codeph>techview</codeph> images
with STAT built in and should launch STAT automatically during start up</note>. </p> <p>For
test execution instructions refer to <xref href="GUID-3C26B5B2-1B90-5F96-9342-1D53F6EDD94F.dita">Base
F32 Test Technology</xref>. To use NAND or NOR configuration of ROM, replace
the buildrom step in the <xref href="GUID-3C26B5B2-1B90-5F96-9342-1D53F6EDD94F.dita">Base
F32 Test Technology</xref> section with the steps listed in the <xref href="GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita#GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6/GUID-3ACBCE43-A041-597C-B201-066002D5A451">NAND configuration ROM</xref> and <xref href="GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita#GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6/GUID-D3A3EE14-8710-5ABF-A1E0-43E2A2B3ED8F">NOR
configuration ROM</xref> respectively. </p> <p id="GUID-3ACBCE43-A041-597C-B201-066002D5A451"><b> NAND configuration ROM </b> </p> <p>To
use a NAND configuration ROM, perform the following steps: </p> <ol id="GUID-5CCCF2E5-6D0F-5A68-A4D5-722BEC025C96">
<li id="GUID-3DFEC3B2-3CB3-52C3-8659-B2760CBAB8CA"><p>Navigate to the <filepath>\epoc32\rom</filepath> directory
and run one of the following commands: </p> <p>if using TestDriver: </p> <p><userinput>buildrom
-D_STARTUPMODE2 -D_NAND2 &lt;h4hrp/h2&gt; techview_statapi</userinput> </p> <p>if
not TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NAND2 &lt;h4hrp/h2&gt;
techview t_base_f32_perf</userinput> </p> <p>This creates two image files, <filepath>h4hrp_001.techview.nand.IMG</filepath> and <filepath>h4hrp_001.techview.nand.rofs.img</filepath>. </p> </li>
<li id="GUID-27AFB5DD-7763-5EFE-87AA-75BD38013203"><p>Rename the two image
files <filepath>h4hrp_001.techview.nand.IMG</filepath> and <filepath>h4hrp_001.techview.nand.rofs.img</filepath> as <filepath>core.img</filepath> and <filepath>rofs1.img</filepath> respectively. </p> </li>
<li id="GUID-CA7E9D84-0C8E-5BD0-B537-B5F3596EB7AE"><p>Navigate to the <filepath>sf/os/kernelhwsrv/kernel/eka/rombuild/...</filepath> directory
and run the following command to generate the <codeph>nandloader</codeph>: </p> <p><userinput>rom
-v=h4hrp -b=urel -i=armv5 -t=nandloader -d=_NAND2</userinput> </p> <p>Successful
execution of this command generates the image file <filepath>H4HRPARMV5.IMG</filepath>  </p> </li>
<li id="GUID-34B34932-9ED0-5091-B694-CA47ABE4C58A"><p>Zip the <filepath>H4HRPARMV5.IMG</filepath> file
rename the zip file to <filepath>sys$rom.zip</filepath>. </p> </li>
<li id="GUID-E4EBB361-6905-531E-9659-1ACD824C4D63"><p>Transfer all three files <filepath>core.img</filepath>, <filepath>rofs1.img</filepath> and <filepath>sys$rom.zip</filepath> to the hardware board using an MMC card or a USB cable. </p> <p>When
the board is restarted with the NAND configuration, the STAT application should
launch automatically into the <i>waiting for data</i> state. If this does
not occur check that the NAND configuration ROM is built correctly and that
you have configured STAT correctly. </p> </li>
</ol> <p id="GUID-D3A3EE14-8710-5ABF-A1E0-43E2A2B3ED8F"><b> NOR configuration ROM</b> </p> <p>To
use a NOR configuration ROM, perform the following steps: </p> <ol id="GUID-842CA0AC-83B7-5D90-844D-FA90945C51F1">
<li id="GUID-38D39DFA-D05F-5940-8831-ED62FD67476A"><p>Navigate to the <filepath>\epoc32\rom</filepath> directory
and run one of the following commands: </p> <p>if using TestDriver: </p> <p><userinput>buildrom
-D_STARTUPMODE2 -D_NOR &lt;h4hrp/h2&gt; techview_statapi</userinput> </p> <p>if
not using TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NOR &lt;h4hrp/h2&gt;
techview pbase-f32-performance</userinput> </p> <p>This creates an image file, <filepath>om_001.techview.IMG</filepath>. </p> </li>
<li id="GUID-C7276BA5-B1D6-5676-9B8C-5AAEFF29DBC2"><p>Zip the <filepath>om_001.techview.IMG</filepath> file
and rename the zip file to <filepath> flashimg.zip</filepath>. </p> </li>
<li id="GUID-7C6030FD-4C66-5A1E-BAF2-3C8766A50896"><p>Transfer this file to
the hardware board using an MMC card or a USB cable. The H4 board boots the
TechView image and loads into NOR-Flash. When the board is booted up the STAT
application should launch automatically into the <i>waiting for data</i> state.
If this does not occur check that the NOR configuration ROM is built correctly
and that you have configured STAT correctly. </p> </li>
</ol> </section>
<section id="GUID-9108BD4B-21E2-414C-A130-756431F3E510"><title>Test results</title> <p>For TEF log files location and general
principles of their interpretation refer to <xref href="GUID-3C26B5B2-1B90-5F96-9342-1D53F6EDD94F.dita">Base
F32 Test Technology</xref>  </p> <p><b> How
to interpret test results</b> </p> <p><b>Interpreting
the HTML logs</b> </p> <p>Each HTML file contains the following information
for each performance test scenario: </p> <ul>
<li id="GUID-6FA8DB6A-E657-5DAC-B8AA-4D7D871B5B00"><p> <b>Number of function
calls is (X):</b> The number of times the API has been called, where x is
an integer. </p> </li>
<li id="GUID-8BB013BD-9EB0-54DC-A53E-A50743913BCC"><p> <b>Time taken for all
function calls (X) microseconds:</b> The total time taken for the API to complete
X number of calls to it, where x is the measured in microseconds. </p> </li>
<li id="GUID-8F38E8E6-8DE3-5638-B79C-6994A4667523"><p> <b> Approximate Average
Time Taken per call (X) microseconds:</b> The average time taken for a call
to the API to complete, where x is the measured in micro seconds. </p> </li>
</ul> <p>RFile API tests only the output information: </p> <ul>
<li id="GUID-A56F9CA1-0073-505F-9F4B-09055B1F70B9"><p> <b>BlockSize (x) bytes:</b> The
buffer size that is read or written to a file, where x is measured in bytes. </p> <p> <b>Note:</b> For <codeph>RFile::Seek</codeph> tests,
this size is zero. </p> </li>
<li id="GUID-54EB0FBF-B8AF-5335-BADC-269AE3E905ED"><p> <b>Bytes processed
(X) bytes:</b> The total number of bytes processed during the test. </p> </li>
<li id="GUID-A651D913-6139-55E6-9246-A9AD56A10FB1"><p> <b>Throughput (X) MB/Sec:</b> The
total amount of data that was processed during the test in one second, where
x is measured in megabytes (MB). </p> </li>
</ul> <p id="GUID-217F088E-D7DD-544A-A7CE-BAABD1BE1491"><b> Interpreting the CSV file
log</b> </p> <p>The <filepath>.CSV</filepath> file also contains the test
results. By default this CSV file is created on the c drive and is called
f32-perfResults, however both the file name and its creation location is configured
using the environment configuration file <filepath>base_perf_f32_env.ini</filepath> for
further details see <xref href="GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita#GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6/GUID-03EBC248-B2FE-5DFF-941A-A386348596B4">Test
Configuration</xref>. </p> <p>It does not indicate whether an individual test
scenario has passed or failed. Instead it contains user friendly performance
data associated with each API test scenario. This data is listed under the
following field headers within the file: </p> <ul>
<li id="GUID-D8B3CF2D-05BC-5837-9FC3-3B0A1CF03CCD"><p> <b>Operation:</b> Indicates
the actual test scenario and lists the API that was tested. For example, <b>ReadXSmallBytes</b> indicates
that the API to be tested is <codeph>RFILE READ: Read (TDes8 &amp;aDes,  
                   TInt aLength)</codeph>. The <b>ReadXSmallBytes</b> test
scenario title indicates that it will be using an extra small number of bytes
(set to 16 bytes by default). </p> </li>
<li id="GUID-3FC64773-6ABA-5D92-8BB7-D33620447986"><p> <b>Calls:</b> Indicates
the number of times this API is called (RFILE READ). </p> </li>
<li id="GUID-E2355EBF-CCE5-5458-B2C7-ECCB4CD1C8A3"><p> <b>Time Taken:</b> Indicates
the total time taken for all calls to that API using the test scenario specified
in the <b>Operation</b> section. This value is represented in microseconds. </p> </li>
<li id="GUID-94AE9913-34A0-5F38-A773-E98F4571B5CB"><p> <b>Average time:</b> Indicates
the average time taken for each individual call to that API using the test
scenario listed in the <b>Operation</b> section. This value is represented
in microseconds. </p> </li>
</ul> <p><b>Interpreting
Anomalies </b> </p> <p>Note that the following behaviour for the <codeph>RFile::Read</codeph> and <codeph>RFile::Write</codeph> APIs
is not true: </p> <ul>
<li id="GUID-2644B902-B669-5CA4-9F76-E93ED0CEF0DF"><p>Read operation + Seek
operation &gt;= Read Seek operation </p> </li>
<li id="GUID-6185CC2B-34B4-53D4-9364-D137A3FA1EEC"><p>Write operation + Seek
operation &gt;= Write Seek operation </p> </li>
</ul> <p>This is because the Symbian platform file system has a client-server
behaviour. A client creates a package for the file server and sends a <b>KCurrentPosition</b> within
that package. In the case of an <codeph>RFile::Read</codeph> or <codeph>RFile::Write</codeph> API
that does not contain a position in its argument. </p> <p>On the server side,
processing this package involves checking whether the position received is
equal to the <b>KCurrentPosition</b>, and if this assignment is true then
the position is assigned a value. This extra assignment gives an overhead.
In both the cases (<codeph>RFile::Read</codeph> and <codeph>RFile::Write</codeph>)
an operation without the position takes a longer time to complete than the
one with a position. </p> </section>
</conbody></concept>