You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.rst
+88-31Lines changed: 88 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,62 +17,114 @@ A microcontroller-friendly fixed-point library specifically designed for embedde
17
17
Description
18
18
===========
19
19
20
-
32-bit and 64-bit fixed-point libraries for fast arithmetic operations. Suitable for performing computationally intensive operations
21
-
on a computing platform that does not have a floating-point unit (like most smaller embedded systems, such as Cortex-M3, CortexM0,
22
-
ATmega, PSoC 5, PSoC 5 LP, PSoC 4, Arduino platforms e.t.c). Common applications include BLDC motor control and image processing.
23
-
Best performance on a 32-bit or higher architecture (although 8-bit architectures should still be fine).
20
+
MFixedPoint is a header-only fixed-point C++ library suitable for fast arithmetic operations on systems which don't have a FPU (e.g. embedded systems). Suitable for performing computationally intensive operations on a computing platform that does not have a floating-point unit (like most smaller embedded systems, such as Cortex-M3, CortexM0, ATmega, PSoC 5, PSoC 5 LP, PSoC 4, Arduino platforms e.t.c). Common applications include BLDC motor control and image processing. Best performance on a 32-bit or higher architecture (although 8-bit architectures should still be fine).
24
21
25
-
The libraries are designed to be a fully-functional data types within their limits (e.g. supports operator overloads and implicit/explicit casting). Can be used with
26
-
most libraries that use data type templates.
22
+
The libraries are designed to be a fully-functional data types within their limits (e.g. supports operator overloads and implicit/explicit casting). Can be used with most libraries that use data type templates.
27
23
28
-
Fixed-point numbers are signed. Q is the number of bits used for the decimal part of the number (the rest are used for the integer part). Q can vary from 0 up to the bit-width of the fixed-point number.
24
+
Fixed-point numbers are signed.
29
25
30
-
The 32-bit Libraries (Fp32f, Fp32s)
31
-
-----------------------------------
26
+
NOTE: This fixed point library will usually be slower when running of a CPU which has associated floating point unit (FPU), e.g. when running on your desktop/laptop. The benchmark performance tests (found in :code:`benchmark/`) suggest simple fixed-point operations such as addition/subtraction/multiplication/division are about 10x slower than their float/double counterparts when there is a FPU. However, this library is designed to be used on CPU's where there is no FPU present. This library comes in useful when there is no FPU present, which is the case for lower-end microcontrollers such as ARM Cortex M0/M3, Atmel ATMEGA, TI MSP430's e.t.c.
32
27
33
-
Intermediary overflows are protected with int64_t casting, end-result overflows will wrap like usual.
28
+
The "Slow" Fixed-Point Library (FpS)
29
+
------------------------------------
34
30
35
-
The 64-bit Libraries (Fp64f, Fp64s)
36
-
-----------------------------------
31
+
The "slow" fixed-point class is called :code:`FpS` (note that this class is not that slow, and is the recommend fixed-point class for almost all use cases). It allows for airthemtic between two fixed-point numbers that have different numbers of fractional bits. The underlying storage type of the fixed-point number and the overflow type are provided as the template parameters.
37
32
38
-
Intermediary overflows are **NOT** protected from overflowing, due to the inability of intermediate casting to:code:`int128_t` on most embedded platforms.
33
+
It is recommended that you use one of the predefined :code:`FpSxx` aliases (available with:code:`#include <MFixedPoint/FpS.h>`), which include:
39
34
40
-
On any 32-bit or lower architecture, 64-bit numbers will be slower than 32-bit numbers. Use only if 32-bit numbers don't offer
41
-
the range/precision required.
35
+
.. code:: cpp
42
36
43
-
The Fast Libraries (Fp32f, Fp64f)
44
-
---------------------------------
37
+
FpS8
38
+
FpS16
39
+
FpS32
40
+
FpS64 // Note: FpS64 is not protected from intermediatary overflows!
45
41
46
-
The number of bits used for the decimal part of the number (Q) is given as a template parameter (e.g. :code:`Fp32f<12>(3.4)` will create the number 3.4 with 12 bits of decimal precision). It is not stored in the fixed-point object. This gives the fastest possible arithmetic speeds, at the expense of loosing some functionality and a tad more code space.
42
+
The number of fractional bits is stored in the fixed-point object (it is a template parameter in the fast library). This gives slightly slower arithmetic speed than the fast library, but allows for more functionality and should use less code space..
47
43
48
-
You have to be aware that when adding numbers with different Q, you have to perform the bit-shifting yourself. Also, if you want to convert a fast fixed-point number to a double, you cannot use a cast (e.g. :code:`(double)myFp32fNum` won't work, you have to use provided functions (e.g. :code:`Fix32ToDouble(myFp32fNum);`).
44
+
The extra functionality includes the ability to add two numbers with a different number of fractional bits transparently, and to ability to cast the fixed-point number into different types (e.g. :code:`(double)myFpSNum` will convert the number to a double).
45
+
46
+
When adding two fixed-point numbers which have a different number of fractional bits, the result's number of fractional bits is always that of lowest of the two operands. For example :code:`FpS32(3.4, 10) + FpS32(1.2, 14)` will result in same object being created as would the code :code:`FpS32(4.6, 10)`.
47
+
48
+
Casting to an :code:`int` rounds to negative infinity; e.g. 5.67 becomes 5, and -12.2 becomes -13.
49
+
50
+
Create a fixed point number:
51
+
52
+
.. code:: cpp
53
+
54
+
#include "MFixedPoint/FpS.hpp"
55
+
56
+
// Create a 32-bit fixed-point number.
57
+
// Assign a value of 12.34
58
+
// Use 8 bits for the fractional part, leaving 24 for the integer part.
The number of bits used for the decimal part of the number (Q) is given as a function argument (e.g. :code:`Fp32s(3.4, 12)` will create the number 3.4 with 12 bits of decimal precision). The Q is stored in the fixed-point object (it is a template parameter in the fast libraries). This gives slightly slower arithmetic speed than the fast libraries, but allows for more functionality and should use less code space..
The extra functionality includes the ability to add two numbers with a different Q transparently, and to ability to cast the fixed-point number into different types (e.g. :code:`(double)myFp32sNum` will convert the number to a double).
83
+
Conversion/Casting:
56
84
57
-
When adding two fixed-point numbers which have a different Q, the result's Q is always that of lowest Q of the two operands. For example :code:`Fp32s(3.4, 10) + Fp32s(1.2, 14)` will result in same object being created as would the code:code:`Fp32s(4.6, 10)`.
85
+
.. code:: cpp
58
86
59
-
Casting to an :code:`int` rounds down to the nearest integer; e.g. 5.67 becomes 5, and -12.2 becomes -13.
87
+
FpS32 fp1(2.22, 8);
88
+
89
+
// Using the ToXXX() functions...
90
+
printf("ToInt<int32_t>() = %i\n", fp1.ToInt<int32_t>()); // Prints "ToInt<int32_t>() = 2"
91
+
printf("ToDouble() = %.2f\n", fp1.ToDouble()); // Prints "ToDouble() = 2.22"
92
+
93
+
// Direct casting is also supported
94
+
printf("(int32_t)fp1 = %i\n", (int32_t)fp1); // Prints "(int32_t)fp1 = 2"
95
+
printf("(double)fp1 = %.2f\n", (double)fp1); // Prints "(double)fp1 = 2.22"
96
+
97
+
98
+
Overflows
99
+
---------
100
+
101
+
:code:`FpS8, FpS16, FpS32` are protected from intermediary overflows. :code:`FpS64` is not, due to the lack of a :code:`int128_t` type on most embeded platforms.
102
+
103
+
On any 32-bit architecture, :code:`FpS64` numbers will be slower than :code:`FpS64` numbers. Use only if 32-bit numbers don't offer the range/precision required.
104
+
105
+
The "Fast" Fixed-Point Library (FpF)
106
+
------------------------------------
107
+
108
+
The number of fractional bits is given as a template parameter (e.g. :code:`FpF<int32_t, 12>(3.4)` will create the number 3.4 with 12 bits of decimal precision). It is not stored in the fixed-point object. This gives the fastest possible arithmetic speeds, at the expense of loosing some functionality and a tad more code space.
109
+
110
+
You have to be aware that when adding numbers with different Q, you have to perform the bit-shifting yourself. Also, if you want to convert a fast fixed-point number to a double, you cannot use a cast (e.g. :code:`(double)myFp32fNum` won't work, you have to use provided functions (e.g. :code:`Fix32ToDouble(myFp32fNum);`).
60
111
61
112
Benchmarking
62
113
============
63
114
64
115
This library contains a benchmarking program in :code:`benchmark/` which runs operations on the fixed-point libraries and reports back on their performance. It is run automatically as part of :code:`make all`.
65
116
66
-
Do not pay much attention to the benchmarking results when run on a pre-emptive OS such as Linux.
117
+
The benchmarking is compared to software-based float arithmetic (using the custom header SoftFloat.hpp), since most benchmarking will be run on a development computer which has an FPU which will be used if float + float was written in code. If benchmarking on a device which does not have an FPU, you should compare the fixed-point operations against the native software float arithmetic implementation instead. Software-based 32-bit float addition and multiplication are performed and compared with the equivalent fixed-point operations.
67
118
68
119
Platform Independent
69
120
====================
70
121
71
122
The library is designed to be platform independent. Port-specific functions are declared in separate files, Port.cpp and Port.hpp. These files include functions for printing debug information. Fill in the functions as desired.
72
123
73
124
This library has been tested on:
74
-
- An ARM Cortex-M3 microcontroller
75
-
- Linux
125
+
126
+
- ARM Cortex-M3 microcontrollers
127
+
- Linux (Ubuntu)
76
128
- A CodeAnywhere "DevBox"
77
129
78
130
Configuration
@@ -88,7 +140,7 @@ Either use cmake with the provided :code:`CMakeLists.txt` in the root directory,
88
140
The cmake method will build the fixed point library and automatically runs all unit tests and the benchmark program.
@@ -99,7 +151,7 @@ The cmake method will build the fixed point library and automatically runs all u
99
151
100
152
You can then the tests by calling:
101
153
102
-
::
154
+
.. code:: bash
103
155
104
156
~/MFixedPoint/build$ ./test/MFixedPointTests
105
157
@@ -108,7 +160,7 @@ Usage
108
160
109
161
See the unit tests in :code:`test/` for more usage examples!
110
162
111
-
::
163
+
.. code:: cpp
112
164
113
165
// Include the API header which provides access to all of the fixed-point
114
166
// data types
@@ -150,6 +202,11 @@ See the unit tests in :code:`test/` for more usage examples!
150
202
return 0;
151
203
}
152
204
205
+
Visual Studio Code
206
+
==================
207
+
208
+
Project files for Visual Studio Code are included in this repository. Include paths have been added to :code:`c_cpp_properties.json` to improve auto-complete. This includes the directory :code:`${workspaceRoot}/build/external/include` (which contains the 3rd party libraries MFixedPoint depends on that are automatically downloaded by CMake) but is only valid once CMake has been run at least once from with a build directory called :code:`build`.
0 commit comments