--- a/Symbian3/SDK/Source/GUID-D525B9A9-6B32-535B-A282-60C85A48D3FB.dita Fri Jul 16 17:23:46 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,123 +0,0 @@
-<?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>
-</conbody></concept>
\ No newline at end of file