lib/libm/man/fma.3

   1 .\" Copyright (c) 2005 David Schultz <das@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: head/lib/msun/man/fma.3 152755 2005-11-24 09:25:10Z joel $
  26 .\"
  27 .Dd December 21, 2011
  28 .Dt FMA 3
  29 .Os
  30 .Sh NAME
  31 .Nm fma ,
  32 .Nm fmaf ,
  33 .Nm fmal
  34 .Nd fused multiply-add
  35 .Sh LIBRARY
  36 .Lb libm
  37 .Sh SYNOPSIS
  38 .In math.h
  39 .Ft double
  40 .Fn fma "double x" "double y" "double z"
  41 .Ft float
  42 .Fn fmaf "float x" "float y" "float z"
  43 .Ft long double
  44 .Fn fmal "long double x" "long double y" "long double z"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn fma ,
  48 .Fn fmaf ,
  49 and
  50 .Fn fmal
  51 functions return
  52 .No "(x * y) + z" ,
  53 computed with only one rounding error.
  54 Using the ordinary multiplication and addition operators, by contrast,
  55 results in two roundings: one for the intermediate product and one for
  56 the final result.
  57 .Pp
  58 For instance, the expression
  59 .No "1.2e100 * 2.0e208 - 1.4e308"
  60 produces \*(If due to overflow in the intermediate product, whereas
  61 .No "fma(1.2e100, 2.0e208, -1.4e308)"
  62 returns approximately 1.0e308.
  63 .Pp
  64 The fused multiply-add operation is often used to improve the
  65 accuracy of calculations such as dot products.
  66 It may also be used to improve performance on machines that implement
  67 it natively.
  68 The macros
  69 .Dv FP_FAST_FMA ,
  70 .Dv FP_FAST_FMAF
  71 and
  72 .Dv FP_FAST_FMAL
  73 may be defined in
  74 .In math.h
  75 to indicate that
  76 .Fn fma ,
  77 .Fn fmaf ,
  78 and
  79 .Fn fmal
  80 (respectively) have comparable or faster speed than a multiply
  81 operation followed by an add operation.
  82 .Sh IMPLEMENTATION NOTES
  83 In general, these routines will behave as one would expect if
  84 .No "x * y + z"
  85 were computed with unbounded precision and range,
  86 then rounded to the precision of the return type.
  87 However, on some platforms, if
  88 .Fa z
  89 is \*(Na, these functions may not raise an exception even
  90 when the computation of
  91 .No "x * y"
  92 would have otherwise generated an invalid exception.
  93 .Sh SEE ALSO
  94 .Xr fenv 3 ,
  95 .Xr math 3
  96 .Sh STANDARDS
  97 The
  98 .Fn fma ,
  99 .Fn fmaf ,
 100 and
 101 .Fn fmal
 102 functions conform to
 103 .St -isoC-99 .
 104 A fused multiply-add operation with virtually identical
 105 characteristics appears in IEEE draft standard 754R.
 106 .Sh HISTORY
 107 These routines first appeared in
 108 .Dx 2.13 .