README.md
1# Description of Apollo3 Makefile targets
2
3* **pushbutton_cmsis_speech_test_bin**:
4 * When users press BTN2 on the Apollo3 EVK, 1 second of audio is captured.
5 * Then the audio is sent to the CMSIS version of the preprocessor and into
6 the neural net
7 * To print out the neural net's inference scores, run GDB and source
8 pushbutton\_cmsis\_scores.cmd
9 * To save the captured audio to a text file (captured\_data.txt), run GDB
10 and source pushbutton\_cmsis\_voice.cmd
11 * Setup python
12 * sudo apt install python-pip
13 * sudo apt install python-tk
14 * pip install numpy
15 * pip install matplotlib
16 * pip install pysoundfile
17 * python captured_data_to_wav.py
18 * captured\_data.txt can be turned into a \*.wav file using
19 captured\_data\_to\_wav.py by executing "python
20 captured\_data\_to\_wav.py"
21* **preprocessor_1k_cmsis_test_bin**:
22 * Sends a 1 kHz sine wave to the CMSIS fixed\_point version of the
23 preprocessor
24 * **This test should be compiled with the -O0 option.** Otherwise, the
25 breakpoints will not be reached
26 * In
27 tensorflow/lite/micro/tools/make/targets/apollo3evb_makefile.inc
28 change "-O3" to "-O0" on line 47
29 * **DO NOT FORGET TO REVERT CHANGE AFTER EXPERIMENT**
30 * In future, enhance scripts to handle automatically, NOT manually!
31 * Clean project by running "make -f
32 tensorflow/lite/micro/tools/make/Makefile clean"
33 * Compile BIN by running "make -f
34 tensorflow/lite/micro/tools/make/Makefile TARGET=apollo3evb
35 preprocessor_1k_cmsis_test_bin"
36 * Run with the preprocessor\_1k\_cmsis\_test.cmd GDB command file
37 * Produces four text files corresponding to outputs from the CMSIS
38 fixed\_point version of this algorithm:
39 * cmsis_windowed_input.txt: the sinusoid after multiplying elementwise
40 with a Hann window
41 * cmsis_dft.txt: the DFT of the windowed sinusoid
42 * cmsis_power.txt: the magnitude squared of the DFT
43 * cmsis_power_avg.txt: the 6-bin average of the magnitude squared of
44 the DFT
45 * Run both versions of the 1KHz pre-processor test and then compare.
46 * These files can be plotted with "python compare\_1k.py"
47 * Also prints out the number of cycles the code took to execute (using the
48 DWT->CYCCNT register)
49* **preprocessor_1k_micro_test_bin**
50 * Sends a 1 kHz sine wave to the Micro-Lite fixed\_point version of the
51 preprocessor
52 * **This test should be compiled with the -O0 option.** Otherwise, the
53 breakpoints will not be reached
54 * Run with the preprocessor\_1k\_micro\_test.cmd GDB command file
55 * Produces four text files corresponding to outputs from the Micro-Lite
56 version of this algorithm:
57 * micro_windowed_input.txt: the sinusoid after multiplying elementwise
58 with a Hann window
59 * micro_dft.txt: the DFT of the windowed sinusoid
60 * micro_power.txt: the magnitude squared of the DFT
61 * micro_power_avg.txt: the 6-bin average of the magnitude squared of
62 the DFT
63 * Run both versions of the 1KHz pre-processor test and then compare.
64 * These files can be plotted with "python compare\_1k.py"
65 * Also prints out the number of cycles the code took to execute (using the
66 DWT->CYCCNT register)
67
68# Description of files
69
70* **.gitignore**: Git should ignore \*.txt and \*.wav files that result from
71 experiments run in this directory
72* **captured\_data\_to\_wav.py**: Python script that parses a text file
73 containing data dumped from GDB (specifically the verilog format) and
74 creates a \*.wav file using
75 [PySoundFile](https://pysoundfile.readthedocs.io/en/0.9.0/).
76* **compare\_1k.py**: This script compares the intermediate variables and
77 final outputs of the micro-lite fixed-point preprocessor function and the
78 CMSIS version of this function. The stimulus provided to each preprocessor
79 is the same: a 1 kHz sinusoid.
80* **get\_yesno\_data.cmd**: A GDB command file that runs preprocessor_test
81 (where TARGET=apollo3evb) and dumps the calculated data for the "yes" and
82 "no" input waveforms to text files
83* **\_main.c**: Point of entry for the micro_speech test
84* **preprocessor_1k.cc**: A version of preprocessor.cc where a 1 kHz sinusoid
85 is provided as input to the preprocessor
86* **preprocessor_1k_cmsis_test.cmd**: GDB command file for the CMSIS
87 preprocessor 1 kHz test
88* **preprocessor_1k_micro_test.cmd**: GDB command file for the Micro-Lite
89 preprocessor 1 kHz test
90* **preprocessor_test.cmd**: GDB command file for the preprocessor test
91* **pushbutton_cmsis_scores.cmd**: GDB command file that runs
92 pushbutton_cmsis_speech_test_bin. It adds a breakpoint immediately after the
93 scores are reported and prints out each score. Then it continues code
94 execution.
95* **pushbutton_cmsis_voice.cmd**: GDB command file that runs
96 pushbutton_cmsis_speech_test_bin. Dumps the recorded 1 second of audio to
97 captured_data.txt, which can then be processed by the python file
98 captured_data_to_wav.py.
99* **pushbutton_main.c**: Source file containing program point of entry
100 \_main() for the pushbutton\_\* tests. Contains Interrupt Service Routines
101 for PDM data capture and pushbuttons. Calls the main() function of
102 pushbutton_test.cc
103* **pushbutton_test.cc**: Source file containing main() function for the
104 pushbutton\_\* tests. main() calls the preprocessor function and the neural
105 net inference function.
106
107# Description of externally downloaded files in ../apollo3_ext
108
109* **apollo3.h**: Apollo 3 version of the
110 [CMSIS Device Header File (device.h)](https://www.keil.com/pack/doc/CMSIS/Core/html/device_h_pg.html).
111 Available in the
112 [Ambiq Keil Pack](http://s3.ambiqmicro.com/pack/AmbiqMicro.Apollo_DFP.1.1.0.pack).
113* **system_apollo3.c**: Apollo 3 version of the
114 [CMSIS System Configuration File system\_\<device\>.c](https://www.keil.com/pack/doc/CMSIS/Core/html/system_c_pg.html).
115 Available in the
116 [Ambiq Keil Pack](http://s3.ambiqmicro.com/pack/AmbiqMicro.Apollo_DFP.1.1.0.pack).
117* **system_apollo3.h**: Apollo 3 version of the
118 [CMSIS System Configuration File system\_\<device\>.h](https://www.keil.com/pack/doc/CMSIS/Core/html/system_c_pg.html).
119 Available in the
120 [Ambiq Keil Pack](http://s3.ambiqmicro.com/pack/AmbiqMicro.Apollo_DFP.1.1.0.pack).
121
122# FFT scaling
123
124See https://github.com/ARM-software/CMSIS_5/issues/220
125
126> And as @xizhizhang pointed, I think there may be an error on the internal
127> downscaling, or at least on the documentation. It looks like during the fft
128> computation, the downscaling factor reach 2**-9 for a 512 rfft operation,
129> being the output in Q10.22, instead the documented 2**-8 and Q9.23.
130