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$ 26.\" 27.Dd January 22, 2005 28.Dt FMA 3 29.Os 30.Sh NAME 31.Nm fma , 32.Nm fmaf 33.Nd fused multiply-add 34.Sh LIBRARY 35.Lb libm 36.Sh SYNOPSIS 37.In math.h 38.Ft double 39.Fn fma "double x" "double y" "double z" 40.Ft float 41.Fn fmaf "float x" "float y" "float z" 42.Sh DESCRIPTION 43The 44.Fn fma 45and 46.Fn fmaf 47functions return 48.No "(x * y) + z" , 49computed with only one rounding error. 50Using the ordinary multiplication and addition operators, by contrast, 51results in two roundings: one for the intermediate product and one for 52the final result. 53.Pp 54For instance, the expression 55.No "1.2e100 * 2.0e208 - 1.4e308" 56produces \*(If due to overflow in the intermediate product, whereas 57.No "fma(1.2e100, 2.0e208, -1.4e308)" 58returns approximately 1.0e308. 59.Pp 60The fused multiply-add operation is often used to improve the 61accuracy of calculations such as dot products. 62It may also be used to improve performance on machines that implement 63it natively. 64The macros 65.Dv FP_FAST_FMA 66and 67.Dv FP_FAST_FMAF 68may be defined in 69.In math.h 70to indicate that 71.Fn fma 72and 73.Fn fmaf 74(respectively) have comparable or faster speed than a multiply 75operation followed by an add operation. 76.Sh IMPLEMENTATION NOTES 77In general, 78.Fn fma 79and 80.Fn fmaf 81will behave as one would expect if 82.No "x * y + z" 83were computed with unbounded precision and range, 84then rounded to the precision of the return type. 85However, on some platforms, if 86.Fa z 87is \*(Na, these functions may not raise an exception even 88when the computation of 89.No "x * y" 90would have otherwise generated an invalid exception. 91.Sh SEE ALSO 92.Xr fenv 3 , 93.Xr math 3 94.Sh STANDARDS 95The 96.Fn fma 97and 98.Fn fmaf 99functions conform to 100.St -isoC-99 . 101A fused multiply-add operation with virtually identical 102characteristics appears in IEEE draft standard 754R. 103.Sh HISTORY 104These routines first appeared in 105.Fx 5.4 . 106