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