From cbd3e07031bca60865ef6c6fd5f3b0c0d5fe296b Mon Sep 17 00:00:00 2001 From: Marcin Maka Date: Mon, 1 Apr 2019 12:15:38 +0200 Subject: [PATCH] tools: doc: README converted to README.md MD content is rendered by GH automatically when listing tools folder. Signed-off-by: Marcin Maka --- tools/README | 138 ----------------------------------------------- tools/README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 141 insertions(+), 138 deletions(-) delete mode 100644 tools/README create mode 100644 tools/README.md diff --git a/tools/README b/tools/README deleted file mode 100644 index defb6ae06..000000000 --- a/tools/README +++ /dev/null @@ -1,138 +0,0 @@ -Sound Open Firmware Tools -========================= - -This is a collection of open source tools used to develop open source audio -DSP firmwares for ALSA. - -Building and Installing -======================= - -mkdir build_tools -cd build_tools -cmake .. -make -make install - -sof-logger -====== - -sof-logger is used to print logs delivered from FW dma_trace mechanism, by searching log -entries in *.ldc file generated by rimage. - -Every entry declared in FW is placed in elf output file (e.g. sof-apl) in -.static_log_entries section in a form of struct defined in sof/src/include/sof/trace.h -in sof fw repo. - -*.ldc file contains snd_sof_logs_header (defined in rmbox/logger_convert.c) -following by .static_log_entries section incorporated from FW elf file (e.g. sof-apl). -snd_sof_logs_header contains basic information about .static_log_entries section -like base_address and data_length. - -sof-logger works by reading entry parameters value and entries addresses from FW -dma_trace mechanism and searching suitable entry in *.ldc file by its address. - -Usage sof-logger - Display mailbox contents --h help --l *.ldc_file Specify the *.ldc file --i in_file Get traces from in_file, instead of the default - "/sys/kernel/debug/sof/etrace" --o out_file Specify the output file, instead of default stdout --t Get traces from "/sys/kernel/debug/sof/trace", instead - of the default "/sys/kernel/debug/sof/etrace" --p Get traces from stdin, instead of the default - "/sys/kernel/debug/sof/etrace" --c Set timestamp clock in MHz --e Enable checking firmware version with default verification file - "/sys/kernel/debug/sof/fw_version" --v ver_file Enable checking firmware version with ver_file file, - instead of default: "/sys/kernel/debug/sof/fw_version" --s Take a snapshot of state - - -Examples: - -- Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw_version with - "/sys/kernel/debug/sof/fw_version" and prints logs to stdout - - $ sof-logger -l ldc_file -e - -- Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw_version with - ver_file file and prints logs to stdout - - $ sof-logger -l ldc_file -v ver_file - -- Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to stdout - - $ sof-logger -l ldc_file - -- Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to - out_file file - - $ sof-logger -l ldc_file -o out_file - -- Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to stdout - - $ sof-logger -l ldc_file -t - -- Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to - out_file file - - $ sof-logger -l ldc_file -t -o out_file - -- Get traces from stdin and prints logs to stdout - - $ sof-logger -l ldc_file -p - -- Get traces from stdin and prints logs to out_file file - - $ sof-logger -l ldc_file -p -o out_file - -- Get traces from trace_dump file and prints logs to stdout - - $ sof-logger -l ldc_file -i trace_dump - -- Get traces from trace_dump file and prints logs to out_file file - - $ sof-logger -l ldc_file -i trace_dump -o out_file - -- c flag is intented for defining clock value (in MHz) used to format log - timestamps. By default clock value is set to 19.2 (MHz). Below example - set clock value to 19.9 (MHz). - - $ sof-logger -l ldc_file -i trace_dump -o out_file -c 19.9 - - -sof-coredump-reader -=================== - -Tool for processing FW stack dumps. In verbose mode it prints the stack leading -to the core dump including DSP registers and function calls. -It outputs unwrapped gdb command function call addresses to human readable -function call format either to a file or stdout. - -Usage sof-coredump-reader.py [-h] [-a ARCH] [-c] [-l COLUMNCOUNT] [-v] - (--stdout | -o OUTFILE) [--stdin | -i INFILE] - --h show this help message and exit --a ARCH determine architecture of dump file; valid archs are: LE64bit, LE32bit --c set output to be colourful --l COLUMNCOUNT set how many colums to group the output in --v increase output verbosity ---stdin input is from stdin --i INFILE path to sys dump bin ---stdout output is to stdout --o OUTFILE output is to FILE - -sof-coredump-to-gdb.sh shows example usage of sof-coredump-reader.py -We read from dump file into sof-coredump-reader.py, -then we pipe its output to xt-gdb, which operates on given elf-file. - - $ ./sof-coredump-to-gdb.sh sof-apl dump_file - -tests -===== - -To generate all test configuration files: - -make tests diff --git a/tools/README.md b/tools/README.md new file mode 100644 index 000000000..b34ccb304 --- /dev/null +++ b/tools/README.md @@ -0,0 +1,141 @@ +# Sound Open Firmware Tools + +This is a collection of open source tools used to develop, test and debug SOF. + +## Building and Installing + +```bash +mkdir build_tools +cd build_tools +cmake .. +make +make install +``` + +### sof-logger + +sof-logger is used to print logs delivered from FW dma_trace mechanism, by +searching log entries in *.ldc file generated by rimage. + +Every entry declared in FW is placed in elf output file (e.g. sof-apl) in +.static_log_entries section in a form of struct defined in +sof/src/include/sof/trace.h in sof fw repo. + +*.ldc file contains `snd_sof_logs_header` (defined in +rmbox/logger\_convert.c) following by `.static_log_entries` section +incorporated from FW elf file (e.g. sof-apl). `snd_sof_logs_header` +contains basic information about `.static_log_entries` section +like `base_address` and `data_length`. + +sof-logger works by reading entry parameters value and entries addresses from +FW dma_trace mechanism and searching suitable entry in *.ldc file by its +address. + +```bash +Usage sof-logger + Display mailbox contents +-h help +-l *.ldc_file Specify the *.ldc file +-i in_file Get traces from in_file, instead of the default + "/sys/kernel/debug/sof/etrace" +-o out_file Specify the output file, instead of default stdout +-t Get traces from "/sys/kernel/debug/sof/trace", instead + of the default "/sys/kernel/debug/sof/etrace" +-p Get traces from stdin, instead of the default + "/sys/kernel/debug/sof/etrace" +-c Set timestamp clock in MHz +-e Enable checking firmware version with default verification file + "/sys/kernel/debug/sof/fw_version" +-v ver_file Enable checking firmware version with ver_file file, + instead of default: "/sys/kernel/debug/sof/fw_version" +-s Take a snapshot of state +``` + +**Examples:** + +Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw\_version with +"/sys/kernel/debug/sof/fw_version" and prints logs to stdout + + $ sof-logger -l ldc_file -e + +Get traces from "/sys/kernel/debug/sof/etrace" file, verifies fw_version with +`ver_file` file and prints logs to stdout + + $ sof-logger -l ldc_file -v ver_file + +Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to stdout + + $ sof-logger -l ldc_file + +Get traces from "/sys/kernel/debug/sof/etrace" file and prints logs to +`out_file` file + + $ sof-logger -l ldc_file -o out_file + +Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to stdout + + $ sof-logger -l ldc_file -t + +Get traces from "/sys/kernel/debug/sof/trace" file and prints logs to +`out_file` file + + $ sof-logger -l ldc_file -t -o out_file + +Get traces from stdin and prints logs to stdout + + $ sof-logger -l ldc_file -p + +Get traces from stdin and prints logs to `out_file` file + + $ sof-logger -l ldc_file -p -o out_file + +Get traces from trace\_dump file and prints logs to stdout + + $ sof-logger -l ldc_file -i trace_dump + +Get traces from trace\_dump file and prints logs to `out_file` file + + $ sof-logger -l ldc_file -i trace_dump -o out_file + +`c` flag is intended for defining clock value (in MHz) used to format log +timestamps. By default clock value is set to 19.2 (MHz). Below example +set clock value to 19.9 (MHz). + + $ sof-logger -l ldc_file -i trace_dump -o out_file -c 19.9 + + +### sof-coredump-reader + +Tool for processing FW stack dumps. In verbose mode it prints the stack leading +to the core dump including DSP registers and function calls. +It outputs unwrapped gdb command function call addresses to human readable +function call format either to a file or stdout. + +```bash +Usage sof-coredump-reader.py [-h] [-a ARCH] [-c] [-l COLUMNCOUNT] [-v] + (--stdout | -o OUTFILE) [--stdin | -i INFILE] + +-h show this help message and exit +-a ARCH determine architecture of dump file; valid archs are: LE64bit, LE32bit +-c set output to be colourful +-l COLUMNCOUNT set how many colums to group the output in +-v increase output verbosity +--stdin input is from stdin +-i INFILE path to sys dump bin +--stdout output is to stdout +-o OUTFILE output is to FILE +``` + +**sof-coredump-to-gdb.sh** shows example usage of sof-coredump-reader.py +We read from dump file into sof-coredump-reader.py, +then we pipe its output to xt-gdb, which operates on given elf-file. + + $ ./sof-coredump-to-gdb.sh sof-apl dump_file + +### tests + +To generate all test configuration files: + +```bash +make tests +```