/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss or reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

/**	@addtogroup math */
/**	@{ */
/**		@defgroup ieee		Manipulations of IEEE-754 format numbers */
/**		@defgroup func		Elementary functions */
/**	@} */

/** @addtogroup math

This library contains a frequently used subset of the standard mathematical
functions.

It is a rule of thumb in embedded system circles that you have
to avoid using float point arithmetics because it is very slow.
Well, it is indeed slower than integer or fixpoint arithmetics, but on
the ARM it's not that bad. The basic float point arithmetics functions
that come with gcc are pretty fast. For many processors they are generated
using generic C functions and thus are indeed slow. For the ARM, however,
gcc builds those functions from handcrafted assembly source, which was
written with speed in mind. Since the transcendental functions spend most
of their time in those low level arithmetic functions (evaluating
approximation polynoms), the efficient low-level arithmetics directly
turns into reasonably fast math functions.
<br><br>
While you probably do not want to do real-time audio processing using the
float point functions, if you need to calculate only a few thousand sines or
exponentials in every second, you can easily do that even in double precision
with only a modest CPU utilisation.<br>
Apart from the transcendental functions, the basic manipulations of
float-point numbers, such as rounding, classification and the like are also
part of the library.<br>
Finally, if speed is a serious concern but you need more than integer
arithmetics, you may want to to take a look at the @ref fixp.
*/

/** @addtogroup func

This is a library of the most frequently used transcendental functions.
Both \p float and \p double versions are provided.
<br><br>
These functions spend most of their time inside the float-point arithmetic
library that comes with gcc. That library is written in assembly, therefore
the execution time of these functions depends very little on whether you
compile them for ARM or for THUMB.
<br><br>
Functions called with invalid arguments will return a non-sgnalling NaN.
There is no other indication of the problem, no facility is provided for you
to set up an exception handler to catch float-point errors. If you need it,
you have to explicitely check the result of the calculations for NaN and raise
the exception yourself.<br>
NaN-s are propagated, therefore on a long calculation chain, if anywhere
in the chain any result was NaN, the end result is also guaranteed to be NaN.
<br><br>
The functions are fairly accurate, but not last-bit accurate. If the last
bit precision would have costed significant amount of runtime, I opted for the
faster version. This means that the transcendental functions can produce a
relative error up to around to 1E-16 for \p doubles and about 5E-7 for
\p floats. In addition, while the \p double version of the trigonometric
functions have proper range reduction, giving you the real result even if
you calculate for example <tt>sin(1E200)</tt>, the \p float version uses a
much simpler (and faster) range reduction method, that is fairly accurate up
to 1E8. Rather than giving you results that are way off, for arguments over
1E8 the \p float trigonometric functions will return NaN-s.
<br><br>
The execution time for some of these functions can be found in the table
below, they were measured on an LPC23xx chip running at 60MHz. Furthermore,
the time needed for the basic float point arithmetic operations (that is,
the routines in gcc's float library) is also provided for reference.

@verbatim
            Execution time of some float-point functions [µs]

Function   +     *     /     sqrt     sin   asin    tan   atan    exp    log
float     1.0   0.9   2.6     2.1      17     26     23     29     20     26
double    1.8   1.7  10.5    10.8      36     66     55     70     43     56
@endverbatim
*/

/** @addtogroup ieee

IEEE-754 format aware functions.

These functions and macros provide access to features that are IEEE-754
format specific and perform basic operations that need to know the actual
internal representation of IEEE-754 numbers. They are pretty simple and
fairly fast.
*/

