From 304ac99a26c0c7ea11150dc2b0a2285e5591fc46 Mon Sep 17 00:00:00 2001 From: Marcin Maka Date: Thu, 11 Oct 2018 17:32:17 +0200 Subject: [PATCH] doc: intro to traces Signed-off-by: Marcin Maka --- developer_guides/debugability/index.rst | 9 ++++ .../traces/images/build-traces.dot | 21 ++++++++ .../traces/images/process-traces.dot | 23 +++++++++ .../traces/images/trace-enable-flow.pu | 13 +++++ .../debugability/traces/index.rst | 48 +++++++++++++++++++ developer_guides/index.rst | 1 + 6 files changed, 115 insertions(+) create mode 100644 developer_guides/debugability/index.rst create mode 100644 developer_guides/debugability/traces/images/build-traces.dot create mode 100644 developer_guides/debugability/traces/images/process-traces.dot create mode 100644 developer_guides/debugability/traces/images/trace-enable-flow.pu create mode 100644 developer_guides/debugability/traces/index.rst diff --git a/developer_guides/debugability/index.rst b/developer_guides/debugability/index.rst new file mode 100644 index 00000000..e3e12e76 --- /dev/null +++ b/developer_guides/debugability/index.rst @@ -0,0 +1,9 @@ +.. _api-debugability: + +Debugability +############ + +.. toctree:: + :maxdepth: 1 + + traces/index diff --git a/developer_guides/debugability/traces/images/build-traces.dot b/developer_guides/debugability/traces/images/build-traces.dot new file mode 100644 index 00000000..cc47b9cb --- /dev/null +++ b/developer_guides/debugability/traces/images/build-traces.dot @@ -0,0 +1,21 @@ +digraph build_proc_traces { + node [shape = record]; + rankdir = LR; + + src [label = "source files\n + \{ trace_event(...) \}"]; + + elf [label = "ELF|.text|.data|...\n\n + |.static_log_entries"]; + + /* compilation & linking */ + src -> elf; + src -> elf:sle [style = dotted, label = "trace\nevent\ndata"] + + /* make bin -> rimage */ + ri [label = "sof- .ri"]; + elf:text -> ri; + elf:data -> ri; + elf:others -> ri; + elf:sle -> lcd_file [style = dotted]; +} diff --git a/developer_guides/debugability/traces/images/process-traces.dot b/developer_guides/debugability/traces/images/process-traces.dot new file mode 100644 index 00000000..9e884540 --- /dev/null +++ b/developer_guides/debugability/traces/images/process-traces.dot @@ -0,0 +1,23 @@ +digraph build_proc_traces { + node [shape = record]; + rankdir = LR; + + ri [label = "sof- .ri"]; + lcd_file; + + dsp [label = "FW\n@ DSP ", style = filled, color = "#92d050"]; + ri -> dsp + + drv [label = "Driver\n@ host", style = filled, color = "#92d050"] + dsp -> drv [style = dashed, label = "<>\ntraces..."]; + + log [label = "/sys/..."]; + drv -> log [style = dashed]; + + log -> logger [style = dashed]; + lcd_file -> logger [style = dotted]; + + logger -> tty [label = "pretty\nprinted\ntraces"]; + + { rank = same; ri; lcd_file } +} diff --git a/developer_guides/debugability/traces/images/trace-enable-flow.pu b/developer_guides/debugability/traces/images/trace-enable-flow.pu new file mode 100644 index 00000000..e2e430bd --- /dev/null +++ b/developer_guides/debugability/traces/images/trace-enable-flow.pu @@ -0,0 +1,13 @@ +participant "Driver" as drv +participant "FW" as fw + +drv <- fw : <> fw ready (fw_version) + activate drv +drv -> drv : remember fw_version + activate drv + deactivate drv +deactivate drv + +... + +drv -> fw : <> dma trace enable diff --git a/developer_guides/debugability/traces/index.rst b/developer_guides/debugability/traces/index.rst new file mode 100644 index 00000000..1df8bf6b --- /dev/null +++ b/developer_guides/debugability/traces/index.rst @@ -0,0 +1,48 @@ +.. _dbg-traces: + +Traces +###### + +A FW developer may log important events by adding ``trace_event(...)`` entries +to the source code. The data is collected in the internal buffer and +transmitted periodically to the host through the DMA. + +Building & Processing Traces +**************************** + +During the compilation and linking, string literals and log entry metadata is +linked to the special *debug* sections that are extracted later to a special +*dictionary* file. This part is not loaded to the DSP and does not occupy the +DSP memory keeping both the memory footprint and the trace DMA payload small. + +.. graphviz:: images/build-traces.dot + :caption: Traces - build process + +Once the binary trace data is received by the host driver, it is accessible to +the trace decoder (logger) through the files located in the +_/sys/kernel/debug/sof/..._. The logger requires the *dictionary* file to +decode the trace data and "printf" them using format specified in the source +files. + +.. graphviz:: images/process-traces.dot + :caption: Traces - running & processing + +Enabling Traces +*************** + +When the traces are enabled by the driver, it stores the FW version information +received along with the *FW Ready* IPC message at the beginning of the local +trace files. It enables simple compatibility check between the trace data and +the *dictionary* file performed by the logger. + +Note that the trace data may be collected on some machine and sent along with +the dictionary file to another person for investigation. It is important to be +able to verify the consistency of both by having the build version attached to +them. + +.. uml:: images/trace-enable-flow.pu + +Adding Traces +************* + +Refer to the *src/include/sof/trace.h*. diff --git a/developer_guides/index.rst b/developer_guides/index.rst index 713879db..5eb9b34b 100644 --- a/developer_guides/index.rst +++ b/developer_guides/index.rst @@ -12,3 +12,4 @@ Developer Guides apps/index unit_tests topology/topology + debugability/index