Diff: DESCRIPTION.txt

Revision:

0:306417d5f0a0

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/DESCRIPTION.txt	Tue Sep 02 05:17:00 2014 +0000
@@ -0,0 +1,81 @@
+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: