<?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 &aDes, TInt aLength) const;

IMPORT_C TInt Write(TDes8 &aDes, TInt aLength) const;

IMPORT_C TInt Write(TInt aPos, TDes8 &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>