--- a/Symbian3/PDK/Source/GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-0B240B41-652F-586A-915E-3D67BFEB8AE6.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,216 +1,216 @@
-<?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 &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 &aName, TEntry &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\<winscw|armv5>\<udeb|urel>\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\<platform>\base_perf_f32_env.ini</filepath> </p> <p>where <codeph><platform></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\<udeb/urel>\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\<winscw|armv5>\<udeb|urel>\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 <h4hrp/h2> techview_statapi</userinput> </p> <p>if
-not TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NAND2 <h4hrp/h2>
-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 <h4hrp/h2> techview_statapi</userinput> </p> <p>if
-not using TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NOR <h4hrp/h2>
-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 &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 >= Read Seek operation </p> </li>
-<li id="GUID-6185CC2B-34B4-53D4-9364-D137A3FA1EEC"><p>Write operation + Seek
-operation >= 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>
+<?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 &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 &aName, TEntry &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\<winscw|armv5>\<udeb|urel>\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\<platform>\base_perf_f32_env.ini</filepath> </p> <p>where <codeph><platform></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\<udeb/urel>\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\<winscw|armv5>\<udeb|urel>\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 <h4hrp/h2> techview_statapi</userinput> </p> <p>if
+not TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NAND2 <h4hrp/h2>
+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 <h4hrp/h2> techview_statapi</userinput> </p> <p>if
+not using TestDriver: </p> <p><userinput>buildrom -D_STARTUPMODE2 -D_NOR <h4hrp/h2>
+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 &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 >= Read Seek operation </p> </li>
+<li id="GUID-6185CC2B-34B4-53D4-9364-D137A3FA1EEC"><p>Write operation + Seek
+operation >= 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>
\ No newline at end of file