1# README
2
3## How to use
4
5This document is explaining how to use cmake with CMSIS-DSP.
6(It is not official so not supported. The official way to build is to use the CMSIS-Pack).
7
8The example arm_variance_f32 in folder Examples/ARM/arm_variance_f32 has been modified to also
9support cmake and is used as an example in this document.
10
11### Generating the Makefiles
12
13To build example arm_variance_f32 with cmake, you need to create a build folder where the build will take place. Don't build in your source directory.
14
15You can create a build folder in Examples/ARM/arm_variance_f32
16
17Once you are in the build folder, you can use cmake to generate the Makefiles.
18
19The cmake command is requiring several arguments. For instance, to build for m7 with AC6 compiler:
20
21    cmake -DCMAKE_PREFIX_PATH="path to compiler (folder containing the bin folder)" \
22    -DCMAKE_TOOLCHAIN_FILE="../../../../armac6.cmake" \
23    -DARM_CPU="cortex-m7" \
24    -DROOT="../../../../../.." \
25    -DPLATFORM="FVP" \
26    -G "Unix Makefiles" ..
27
28DCMAKE_PREFIX_PATH is the path to the compiler toolchain. This folder should contain the bin folder where are the compiler executables.
29
30ROOT is pointing to the root CMSIS folder (the one containing CMSIS and Device).
31
32PLATFORM is used to select the boot code for the example. In example below, Fast Model (FVP) is selected and the boot code for fast model will be used.
33
34CMAKE_TOOLCHAIN_FILE is selecting the toolchain (ac6, ac5 or gcc). The files are in CMSIS/DSP.
35
36ARM_CPU is selecting the core. The syntax must be the one recognized by the compiler.
37(So for instance different between AC5 and AC6).
38
39The final .. is the path to the directory containing the CMakeLists.txt of the variance example.
40Since the build folder is assumed to be created in arm_variance_examples then the path to CMakeLists.txt from the build folder is ..
41
42To build for A5, you need to change DCMAKE_TOOLCHAIN_FILE and ARM_CPU:
43
44    -DCMAKE_TOOLCHAIN_FILE=../../../../armac5.cmake
45    -DARM_CPU="cortex-a5"
46
47To build for A5 with Neon acceleration, you need to add:
48
49    -DNEON=ON
50
51### Building
52
53Once cmake has generated the makefiles, you can use a GNU Make to build.
54
55    make VERBOSE=1
56
57### Running
58
59The generated executable can be run on a fast model.
60For instance, if you built for m7, you could just do:
61
62    FVP_MPS2_Cortex-M7.exe -a arm_variance_example
63
64The final executable has no extension in the filename.
65
66## Building only the CMSIS-DSP library
67
68If you want to build only the CMSIS-DSP library and don't link with any boot code then you'll need to write a specific cmake.
69
70Create a folder BuildCMSISOnly.
71
72Inside the folder, create a CMakeLists.txt with the following content:
73
74```cmake
75cmake_minimum_required (VERSION 3.14)
76
77# Define the project
78project (testcmsisdsp VERSION 0.1)
79
80# Define the path to CMSIS-DSP (ROOT is defined on command line when using cmake)
81set(DSP ${ROOT}/CMSIS/DSP)
82
83# Add DSP folder to module path
84list(APPEND CMAKE_MODULE_PATH ${DSP})
85
86###########
87#
88# CMSIS DSP
89#
90
91# Load CMSIS-DSP definitions. Libraries will be built in bin_dsp
92add_subdirectory(${DSP}/Source bin_dsp)
93```
94
95Create a build folder inside the BuildCMSISOnly folder.
96
97Inside the build folder, type following cmake command
98
99    cmake -DROOT="path to CMSIS Root" \
100      -DCMAKE_PREFIX_PATH="path to compiler (folder containing the bin folder)" \
101      -DCMAKE_TOOLCHAIN_FILE="../../CMSIS_ROOT/CMSIS/DSP/armac6.cmake" \
102      -DARM_CPU="cortex-m7" \
103      -G "Unix Makefiles" ..
104
105Now you can make:
106
107    make VERBOSE=1
108
109When the build has finished, you'll have a bin_dsp folder inside your build folder.
110Inside bin_dsp, you'll have a folder per CMSIS-DSP Folder : BasicMathFunctions ...
111
112Inside each of those folders, you'll  have a library : libCMSISDSPBasicMath.a ...
113
114
115
116## Compilation symbols for tables
117
118Some new compilations symbols have been introduced to avoid including all the tables if they are not needed.
119
120If no new symbol is defined, everything will behave as usual. If ARM_DSP_CONFIG_TABLES is defined then the new symbols will be taken into account.
121
122Then you can select all FFT tables or all interpolation tables by defining following compilation symbols:
123
124* ARM_ALL_FFT_TABLES : All FFT tables are included
125* ARM_ALL_FAST_TABLES : All interpolation tables are included
126
127If more control is required, there are other symbols but it is not always easy to know which ones need to be enabled for a given use case.
128
129If you use cmake, it is easy since high level options are defined and they will select the right compilation symbols. If you don't use cmake, you can just look at fft.cmake to see which compilation symbols are needed.
130
131For instance, if you want to use the arm_rfft_fast_f32, in fft.cmake you'll see an option RFFT_FAST_F32_32.
132
133We see that following symbols need to be enabled :
134
135* ARM_TABLE_TWIDDLECOEF_F32_16
136* ARM_TABLE_BITREVIDX_FLT_16
137* ARM_TABLE_TWIDDLECOEF_RFFT_F32_32
138* ARM_TABLE_TWIDDLECOEF_F32_16
139
140In addition to that, ARM_DSP_CONFIG_TABLES must be enabled and finally ARM_FFT_ALLOW_TABLES must also be defined.
141
142This last symbol is required because if no transform functions are included in the build, then by default all flags related to FFT tables are ignored.
143
144
145## Bit Reverse Tables CMSIS DSP
146
147It is a question coming often.
148
149It is now detailed [in this github issue](https://github.com/ARM-software/CMSIS_5/issues/858)
150
151Someone from the community has written a [Python script to help](https://gist.github.com/rosek86/d0d709852fddf36193071d7f61987bae)