1# Sound Open Firmware Tools
2
3This is a collection of open source tools used to develop, test and debug SOF.
4
5## Building and Installing
6
7```bash
8mkdir build_tools
9cd build_tools
10cmake ..
11make
12make install
13```
14
15### sof-logger
16
17sof-logger is used to print logs delivered from FW dma_trace mechanism, by
18searching log entries in *.ldc file generated by smex.
19
20Every entry declared in FW is placed in elf output file (e.g. sof-tgl) in
21.static_log_entries section in a form of struct defined in
22sof/src/include/sof/trace.h in sof fw repo.
23
24*.ldc file contains `snd_sof_logs_header` (defined in
25rmbox/logger\_convert.c) following by `.static_log_entries` section
26incorporated from FW elf file (e.g. sof-tgl). `snd_sof_logs_header`
27contains basic information about `.static_log_entries` section
28like `base_address` and `data_length`.
29
30sof-logger works by reading entry parameters value and entries addresses from
31FW dma_trace mechanism and searching suitable entry in *.ldc file by its
32address.
33
34```
35Usage sof-logger <option(s)> <file(s)>
36			Display mailbox contents
37-h			help
38-l *.ldc_file		Specify the *.ldc file
39-i in_file		Get traces from in_file, instead of the default
40			"/sys/kernel/debug/sof/etrace"
41-o out_file		Specify the output file, instead of default stdout
42-t			Get traces from "/sys/kernel/debug/sof/trace", instead
43			of the default "/sys/kernel/debug/sof/etrace"
44-u baud			Input data from a UART
45-r			Less formatted output for chained log processors
46-p			Get traces from stdin, instead of the default
47			"/sys/kernel/debug/sof/etrace"
48-c			Set timestamp clock in MHz
49-e			Enable checking firmware version with default verification file
50			"/sys/kernel/debug/sof/fw_version"
51-v ver_file		Enable checking firmware version with ver_file file,
52			instead of default: "/sys/kernel/debug/sof/fw_version"
53-s state_name		Take a snapshot of state. Save the debugfs entries in
54			state_name.*.txt.
55```
56
57**Examples:**
58
59Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw\_version with
60"/sys/kernel/debug/sof/fw_version" and prints logs to stdout
61
62	$ sof-logger -l ldc_file -e
63
64Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw_version with
65`ver_file` file and prints logs to stdout
66
67	$ sof-logger -l ldc_file -v ver_file
68
69Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to stdout
70
71	$ sof-logger -l ldc_file
72
73Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to
74`out_file` file
75
76	$ sof-logger -l ldc_file -o out_file
77
78Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to stdout
79
80	$ sof-logger -l ldc_file -t
81
82Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to
83`out_file` file
84
85	$ sof-logger -l ldc_file -t -o out_file
86
87Get traces from stdin and prints logs to stdout
88
89	$ sof-logger -l ldc_file -p
90
91Get traces from stdin and prints logs to `out_file` file
92
93	$ sof-logger -l ldc_file -p -o out_file
94
95Get traces from trace\_dump file and prints logs to stdout
96
97	$ sof-logger -l ldc_file -i trace_dump
98
99Get traces from trace\_dump file and prints logs to `out_file` file
100
101	$ sof-logger -l ldc_file -i trace_dump -o out_file
102
103`c` flag is intended for defining clock value (in MHz) used to format log
104timestamps. By default clock value is set to 19.2 (MHz). Below example
105set clock value to 19.9 (MHz).
106
107	$ sof-logger -l ldc_file -i trace_dump -o out_file -c 19.9
108
109
110### sof-coredump-reader
111
112Tool for processing FW stack dumps. In verbose mode it prints the stack leading
113to the core dump including DSP registers and function calls.
114It outputs unwrapped gdb command function call addresses to human readable
115function call format either to a file or stdout.
116
117```
118Usage sof-coredump-reader.py [-h] [-a ARCH] [-c] [-l COLUMNCOUNT] [-v]
119				(--stdout | -o OUTFILE) [--stdin | -i INFILE]
120
121-h			show this help message and exit
122-a ARCH			determine architecture of dump file; valid archs are: LE64bit, LE32bit
123-c			set output to be colourful
124-l COLUMNCOUNT		set how many colums to group the output in
125-v			increase output verbosity
126--stdin			input is from stdin
127-i INFILE		path to sys dump bin
128--stdout		output is to stdout
129-o OUTFILE		output is to FILE
130```
131
132**sof-coredump-to-gdb.sh** shows example usage of sof-coredump-reader.py
133We read from dump file into sof-coredump-reader.py,
134then we pipe its output to xt-gdb, which operates on given elf-file.
135
136    $ ./sof-coredump-to-gdb.sh sof-tgl dump_file
137
138### tests
139
140To generate all test configuration files:
141
142```bash
143make tests
144```
145
146### testbench
147
148The host testbench is meant to serve as a vehicle to test components for
149functionality and quality of processed samples.
150
151#### Compilation steps
152
153Run the rebuild-testbench.sh to build the required libraries for the testbench.
154It should also build the testbench executable.
155
156#### Running the Testbench
157
158The test can be invoked by running the "testbench" bin in the src/host
159directory.
160
161Compile and run using script provided (Recommended):
162
163Set up the input arguments for the test in
164**host-testbench.sh** and invoke it to compile the host libraries
165and execute the testbench.
166
167Known Limitations:
168
1691. Currently, testbench code supports simple volume topologies only.
170
1712. When setting up arguments, please keep the same file format for input and output files
172