doc: intro to traces

developer_guides/debugability/index.rst

@@ -0,0 +1,9 @@
+.. _api-debugability:
+
+Debugability
+############
+
+.. toctree::
+   :maxdepth: 1
+
+   traces/index

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>.text|<data>.data|<others>...\n\n
+                  |<sle>.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];
+}

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 = "<<dma>>\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 }
+}

developer_guides/debugability/traces/images/trace-enable-flow.pu

@@ -0,0 +1,13 @@
+participant "Driver" as drv
+participant "FW" as fw
+
+drv <- fw : <<IPC>> fw ready (fw_version)
+   activate drv
+drv -> drv : remember fw_version
+   activate drv
+   deactivate drv
+deactivate drv
+
+...
+
+drv -> fw : <<IPC>> dma trace enable

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*.

developer_guides/index.rst

@@ -12,3 +12,4 @@ Developer Guides
    apps/index
    unit_tests
    topology/topology
+   debugability/index