<?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-D525B9A9-6B32-535B-A282-60C85A48D3FB" xml:lang="en"><title>Floating

point support</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>ARM provide a hardware floating point coprocessor that provides floating

point computation that is fully compliant with IEEE Std 754-1985. This is

an implementation of the ARM Vector Floating Point Architecture (VFPv2). We

refer to the coprocessor as the <i>VFP unit</i>. </p>

<p>Symbian platform supports the use of VFPv2 on platforms where the required

hardware is present in both <i>RunFast</i> mode and in <i>IEEE-without-exceptions</i> mode.

See ARM's Vector Floating-point Coprocessor Technical reference Manual for

more details on the coprocessor, its architecture, and its execution modes. </p>

<p>Note that Symbian platform does not support floating point exceptions in

any mode. </p>

<ul>

<li id="GUID-4427B5C6-BB5D-5166-8E29-05E7744B8091"><p><xref href="GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB.dita#GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB/GUID-00C045C3-2760-56E0-A8BB-F4D23E0230F2">Using the Vector Floating Point Architecture (VFP) in an application</xref>  </p> </li>

<li id="GUID-B3845C41-B553-54A8-87ED-3B439DCF2F2D"><p><xref href="GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB.dita#GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB/GUID-7E2C76D4-8511-528C-9FA5-ED64F93175A0">Run time check for hardware floating point</xref>  </p> </li>

<li id="GUID-E71E5EBA-6421-5EBA-8C93-0F31F445C79B"><p><xref href="GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB.dita#GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB/GUID-AE954A2C-1E16-5361-A464-9FD2FFFEA40A">Execution modes</xref>  </p> </li>

</ul>

<section id="GUID-00C045C3-2760-56E0-A8BB-F4D23E0230F2"><title>Using the Vector

Floating Point Architecture (VFP) in an application</title> <p>An application

can use VFP in two ways: </p> <ul>

<li id="GUID-A92CC6A6-7C06-569B-9A7B-1BECF7795F9D"><p>indirectly through the

use of floating point support functions. </p> </li>

<li id="GUID-7B5D5A48-5479-577A-A611-74B5E872C01A"><p>directly in its code,

either generated by the compiler, or hand-written in assembler. </p> </li>

</ul> <p><b>Indirect use</b> </p> <p>By default, all applications are built

to use the floating point support functions. </p> <p>On a device without a

VFP unit, floating point support functions are implemented in software and

operate slowly. On a device with a VFP unit, the floating point support functions

are handled by the VFP unit, and operate faster than when implemented in software. </p> <p>Note

that applications do not need to make any changes to take advantage of VFP-enabled

floating point support functions, if they are provided in the device's ROM.

Such functions are used automatically at run time. </p> <p><b>Direct use</b> </p> <p>To

generate VFP <i>specific</i> code at <i>compile</i> time, you need to add

the <xref href="GUID-947317B7-7E12-509B-9A16-F0604D7F8BA2.dita">armfpu</xref> statement

with the <codeph>vfpv2</codeph> keyword into your <filepath>.mmp</filepath> file: </p> <codeblock id="GUID-F7480C2F-1DF9-554B-BB36-4A02D8D72697" xml:space="preserve">armfpu vfpv2</codeblock> <p>On

a device with a VFP unit, this option results in code that runs faster than

the floating point support functions generated by <codeph>armfpu         

    softvfp</codeph>. Note, however, that binaries generated with VFP specific

code do not work on devices without a VFP unit - any call to VFP specific

code results in a KERN-EXEC 3 panic. </p> <p>On those devices that have a

VFP unit, the functions supplied in the <xref href="GUID-1DB7AE7A-A505-3530-AC2B-EBAEFCD3F36A.dita"><apiname>Math</apiname></xref> class, that

perform trigonometric and transcendental operations may also be implemented

using VFP specific code. This is transparent to application code. </p> </section>

<section id="GUID-7E2C76D4-8511-528C-9FA5-ED64F93175A0"><title>Run time check

for hardware floating point</title> <p>An application can find out at run

time whether a device supports hardware floating point by calling <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref>,

using the <xref href="GUID-6476C061-E2DB-3167-8556-DAECEE8EB82A.dita"><apiname>EHardwareFloatingPoint</apiname></xref> attribute. The following

code fragment shows how you would do this: </p> <codeblock id="GUID-821A924B-9898-5E2B-A65C-C2D270B296CF" xml:space="preserve">...

TInt supportedFp;

TInt HalVfp = HAL::Get(HALData::EHardwareFloatingPoint, supportedFp);

if (HalVfp == KErrNone && (supportedFp & EFpTypeVFPv2))

    {

    // HAL says that we have a VFP unit

    ...

    }

else

    {

    // HAL says that we do NOT have a VFP unit

    ...

    }

...        

    </codeblock> <p>Note that, strictly speaking, the return value from <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> indicates

whether or not the attribute is supported. To deduce whether hardware floating

point is supported by the device, the following logic applies: </p> <ul>

<li id="GUID-30F1BC25-CF7A-590A-B2C3-F361C7AD8DA4"><p>If the Hardware Abstraction

Layer (HAL) does not support the <xref href="GUID-6476C061-E2DB-3167-8556-DAECEE8EB82A.dita"><apiname>EHardwareFloatingPoint</apiname></xref> attribute,

then <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>.

This can be interpreted as meaning that the device does not support hardware

floating point. </p> </li>

<li id="GUID-DDCB753F-E958-53E4-BC36-66C22162AD3B"><p>If the HAL does support

the <xref href="GUID-6476C061-E2DB-3167-8556-DAECEE8EB82A.dita"><apiname>EHardwareFloatingPoint</apiname></xref> attribute, then <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> returns <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref>.

In this case the <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> variable <codeph>supportedTypes</codeph> in

the above example code fragment will contain an enum value of type <xref href="GUID-CA12EA77-2DBA-3214-8E62-0D7A51913DE3.dita"><apiname>TFloatingPointType</apiname></xref> describing

the type of hardware floating point supported. If hardware floating point

is supported, then currently, this can only be ARM Vector Floating Point Architecture

(VFPv2) as indicated by the <xref href="GUID-6416724B-8537-3A01-893F-88C5E7130CE7.dita"><apiname>EFpTypeVFPv2</apiname></xref> enum value. </p> </li>

</ul> </section>

<section id="GUID-AE954A2C-1E16-5361-A464-9FD2FFFEA40A"><title>Execution modes</title> <p>Symbian

platform can support the two execution modes: <codeph>RunFast</codeph> and <codeph>IEEE-without-exceptions</codeph>. </p> <table id="GUID-6BAE9BC4-8961-54CE-9CFF-477392DF53A7">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <codeph>RunFast</codeph>  </p> </entry>

<entry><p>In this mode, denormalised numbers, i.e. those outside the range

of normal floating point values, are treated as zero, and a default <codeph>NaN</codeph> (<i>Not

a Number</i>) value is used for all <codeph>NaN</codeph> situations regardless

of the inputs. </p> </entry>

</row>

<row>

<entry><p> <codeph>IEEE-without-exceptions</codeph>  </p> </entry>

<entry><p>In this mode, denormalised numbers are treated as their actual values,

and the IEEE754-mandated values for <codeph>NaN</codeph> s are used. </p> <p>The

floating point model mandated by the Java specification is identical to this

mode, and means that this mode is sufficient to implement a VFP-accelerated

JVM. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>An application can set (and check) the execution mode at run time

by calling <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-79902CB3-FD04-3F31-8196-995B004CF116"><apiname>User::SetFloatingPointMode()</apiname></xref>, and passing one

of the <xref href="GUID-C71880A1-308E-36B6-BBAC-232513868921.dita"><apiname>TFloatingPointMode</apiname></xref> enum values, which represent

the possible modes. </p> <p>The function can still be used even if hardware

floating point is not supported. In this case it returns <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p>Applications

that do not require <codeph>NaN</codeph> values to be as specified by IEEE754

and are not concerned with accuracy when dealing with very small (denormalised)

quantities, can select <codeph>RunFast</codeph> mode for a possible performance

increase. Games or 3D engines are likely to fall into this category. Applications

that require accurate IEEE754 interpretations, such as the JVM, can explicitly

select <codeph>IEEE-without-exceptions</codeph> mode, and if this fails as

being unsupported, refuse to run. </p> </section>