1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB" xml:lang="en"><title>Floating

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

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

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

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

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

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

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

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

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

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

    23 any mode. </p>

    24 <ul>

    25 <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>

    26 <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>

    27 <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>

    28 </ul>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    46 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

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

    48 the floating point support functions generated by <codeph>armfpu         

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

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

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

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

    53 perform trigonometric and transcendental operations may also be implemented

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

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

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

    57 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>,

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

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

    60 TInt supportedFp;

    61 

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

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

    64     {

    65     // HAL says that we have a VFP unit

    66     ...

    67     }

    68 else

    69     {

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

    71     ...

    72     }

    73 ...        

    74     </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

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

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

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

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

    79 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>.

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

    81 floating point. </p> </li>

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

    83 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>.

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

    85 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

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

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

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

    89 </ul> </section>

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

    91 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">

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

    93 <tbody>

    94 <row>

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

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

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

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

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

   100 </row>

   101 <row>

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

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

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

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

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

   107 JVM. </p> </entry>

   108 </row>

   109 </tbody>

   110 </tgroup>

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

   112 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

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

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

   115 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

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

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

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

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

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

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

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

   123 </conbody></concept>