Chapter 4. API Guides
esp apptrace start file://trace.log 1 -1 -1 0 0
There is no limitation on the size of collected data and there is no any data timeout set. This process may be
stopped by issuing esp apptrace stop command on OpenOCD telnet prompt, or by pressing Ctrl+C in
OpenOCD window.
3. Retrieve tracing data and save them indefinitely.
esp apptrace start file://trace.log 0 -1 -1 0 0
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing press
Ctrl+C in OpenOCD window.
4. Wait for target to be halted. Then resume target’s operation and start data retrieval. Stop after collecting 2048
bytes of data:
esp apptrace start file://trace.log 0 2048 -1 1 0
To configure tracing immediately after reset use the openocd reset halt command.
Logging to Host
IDF implements useful feature: logging to host via application level tracing library. This is a kind of semihosting
when all ESP_LOGx calls send strings to be printed to the host instead of UART. This can be useful because“printing
to host”eliminates some steps performed when logging to UART. The most part of work is done on the host.
By default IDF’s logging library uses vprintf-like function to write formatted output to dedicated UART. In general
it involves the following steps:
1. Format string is parsed to obtain type of each argument.
2. According to its type every argument is converted to string representation.
3. Format string combined with converted arguments is sent to UART.
Though implementation of vprintf-like function can be optimized to a certain level, all steps above have to be per-
formed in any case and every step takes some time (especially item 3). So it frequently occurs that with additional log
added to the program to identify the problem, the program behavior is changed and the problem cannot be reproduced
or in the worst cases the program cannot work normally at all and ends up with an error or even hangs.
Possible ways to overcome this problem are to use higher UART bitrates (or another faster interface) and/or move
string formatting procedure to the host.
Application level tracing feature can be used to transfer log information to host using esp_apptrace_vprintf
function. This function does not perform full parsing of the format string and arguments, instead it just calculates
number of arguments passed and sends them along with the format string address to the host. On the host log data
are processed and printed out by a special Python script.
Limitations Current implementation of logging over JTAG has some limitations:
1. Tracing from ESP_EARLY_LOGx macros is not supported.
2. No support for printf arguments which size exceeds 4 bytes (e.g. double and uint64_t).
3. Only strings from .rodata section are supported as format strings and arguments.
4. Maximum number of printf arguments is 256.
How To Use It In order to use logging via trace module user needs to perform the following steps:
1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this func-
tion is esp_apptrace_vprintf. It sends log data to the host. Example code is provided in sys-
tem/app_trace_to_host.
2. Follow instructions in items 2-5 in Application Specific Tracing.
3. To print out collected log records, run the following command in terminal: $IDF_PATH/tools/
esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/
elf/file.
Espressif Systems 1258
Submit Document Feedback
Release v4.4