<?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 &amp;&amp; (supportedFp &amp; 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>
</conbody></concept>