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