File content as of revision 1:ab4d55399b01:

Description

s16math is a compact library of 16 bit fixed point[1] math functions
for microcontroller - MCU - environments without fixed or floating
point hardware.

The development platform is Debian Linux running on an X86 machine
using basic GNU/Linux cross compilation development tools. The package
provides tools to build deployable object versions of the library for a
variety of targets.

Capabilities are focused on processor and memory constrained embedded
applications such as resource limited battery powered sensors and
wearable medical devices. MCUs such as the HC08, HC11, 8051, Z80, and
ARM machines operating in 16-bit mode are supported, maximizing use of
limited MCU registers while minimizing the software overhead of 32 and
64 bit operations.

The trigonometric and math functions make the library well suited for
software defined radio - SDR - signal management requirements.

The virtual fixed point format provides 65,536 discrete signed values
between -32768 and +32767 inclusive, with an equivalent decimal fixed
point range of -327.68 through +327.67. If binary resolution is used,
the range is -256.000 through +255.127 (see text on dot (".") notation
below). If your application requires numbers outside this range, then
this masterpiece - alas - is not for you.

Machine level integers are treated as virtual fixed point[1] numbers
with sign, integer, and fractional parts specified in either decimal or
Qm.n[2] format. The most significant bit is the sign bit, leaving 15
bits to be allocated between the integer and the fractional components.

Numbers are a ratio of two integers: the numerator is kept in storage,
the denominator is implied and is equal to either a power of 10 or a
power of 2. The integer and fractional parts are given by the integer
division of the whole number by the denominator: the integer portion is
the quotient and the fractional part is the remainder. A dot (".")
notation is used to separate the integer and fractional portions of the
number when it is displayed.

If exact fractional powers of ten are desired, then a decimal format
should be used[1]. This provides more range than the binary format, but
less resolution.

So where the denominator is 100, the number 30 is treated as 30/100, or
2.30; 250 is treated as 250/100, or 2.50. In this library, denominators
of 10, 100, and 1000 are used.

In Qm.n format 'm' is the number of bits in the integer portion of the
number, and 'n' is the number of bits in the fractional part. The
denominator is a constant equal to 2^n[2].

So where n is 6, 2^n is 64, and the number 30 is treated as 30/64
(0.30); 250 is treated as 250/64, or 3 58/64 (3.58). Where n is 7, 2^n
is 128, and the number 30 is treated as 30/128 (0.030); 250 is treated
as 250/128, or 1 122/128 (1.122) etc. In this library, Q11.4, Q8.7, and
Q6.9 formats are used.

The advantage of the Qm.n format is that the rounding operations needed
to preserve precision may be done with bit shifts instead of division
and multiplication, which can significantly boost performance and save
code overhead in machines without integer multiplication and division
hardware.

Installation

The download file unpacks into a directory named "eval". So change to
the directory where you wish to install it, download the zip file and
unzip it.

You should now see the subdirectory "eval". Go there. Peruse README.
Alternately, point your browser to eval/html and peruse README.html.
Proceed thence.

[1] Fixed-point arithmetic
    http://en.wikipedia.org/wiki/Fixed-point_arithmetic

[2] Q (number format)
    http://en.wikipedia.org/wiki/Q_%28number_format%29
# vi:set expandtab: