diff options
| -rw-r--r-- | Documentation/guides/tracing.rst | 141 | ||||
| -rw-r--r-- | Documentation/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/meson.build | 1 |
3 files changed, 143 insertions, 0 deletions
diff --git a/Documentation/guides/tracing.rst b/Documentation/guides/tracing.rst new file mode 100644 index 00000000..9c688b93 --- /dev/null +++ b/Documentation/guides/tracing.rst @@ -0,0 +1,141 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Tracing Guide +============= + +Guide to tracing in libcamera. + +Profiling vs Tracing +-------------------- + +Tracing is recording timestamps at specific locations. libcamera provides a +tracing facility. This guide shows how to use this tracing facility. + +Tracing should not be confused with profiling, which samples execution +at periodic points in time. This can be done with other tools such as +callgrind, perf, gprof, etc., without modification to the application, +and is out of scope for this guide. + +Compiling +--------- + +To compile libcamera with tracing support, it must be enabled through the +meson ``tracing`` option. It depends on the lttng-ust library (available in the +``liblttng-ust-dev`` package for Debian-based distributions). +By default the tracing option in meson is set to ``auto``, so if +liblttng is detected, it will be enabled by default. Conversely, if the option +is set to disabled, then libcamera will be compiled without tracing support. + +Defining tracepoints +-------------------- + +libcamera already contains a set of tracepoints. To define additional +tracepoints, create a file +``include/libcamera/internal/tracepoints/{file}.tp``, where ``file`` is a +reasonable name related to the category of tracepoints that you wish to +define. For example, the tracepoints file for the Request object is called +``request.tp``. An entry for this file must be added in +``include/libcamera/internal/tracepoints/meson.build``. + +In this tracepoints file, define your tracepoints `as mandated by lttng +<https://lttng.org/man/3/lttng-ust>`_. The header boilerplate must *not* be +included (as it will conflict with the rest of our infrastructure), and +only the tracepoint definitions (with the ``TRACEPOINT_*`` macros) should be +included. + +All tracepoint providers shall be ``libcamera``. According to lttng, the +tracepoint provider should be per-project; this is the rationale for this +decision. To group tracepoint events, we recommend using +``{class_name}_{tracepoint_name}``, for example, ``request_construct`` for a +tracepoint for the constructor of the Request class. + +Tracepoint arguments may take C++ objects pointers, in which case the usual +C++ namespacing rules apply. The header that contains the necessary class +definitions must be included at the top of the tracepoint provider file. + +Note: the final parameter in ``TP_ARGS`` *must not* have a trailing comma, and +the parameters to ``TP_FIELDS`` are *space-separated*. Not following these will +cause compilation errors. + +Using tracepoints (in libcamera) +-------------------------------- + +To use tracepoints in libcamera, first the header needs to be included: + +``#include "libcamera/internal/tracepoints.h"`` + +Then to use the tracepoint: + +``LIBCAMERA_TRACEPOINT({tracepoint_event}, args...)`` + +This macro must be used, as opposed to lttng's macros directly, because +lttng is an optional dependency of libcamera, so the code must compile and run +even when lttng is not present or when tracing is disabled. + +The tracepoint provider name, as declared in the tracepoint definition, is not +included in the parameters of the tracepoint. + +There are also two special tracepoints available for tracing IPA calls: + +``LIBCAMERA_TRACEPOINT_IPA_BEGIN({pipeline_name}, {ipa_function})`` + +``LIBCAMERA_TRACEPOINT_IPA_END({pipeline_name}, {ipa_function})`` + +These shall be placed where an IPA function is called from the pipeline handler, +and when the pipeline handler receives the corresponding response from the IPA, +respectively. These are the tracepoints that our sample analysis script +(see "Analyzing a trace") scans for when computing statistics on IPA call time. + +Using tracepoints (from an application) +--------------------------------------- + +As applications are not part of libcamera, but rather users of libcamera, +applications should seek their own tracing mechanisms. For ease of tracing +the application alongside tracing libcamera, it is recommended to also +`use lttng <https://lttng.org/docs/#doc-tracing-your-own-user-application>`_. + +Using tracepoints (from closed-source IPA) +------------------------------------------ + +Similar to applications, closed-source IPAs can simply use lttng on their own, +or any other tracing mechanism if desired. + +Collecting a trace +------------------ + +A trace can be collected fairly simply from lttng: + +.. code-block:: bash + + lttng create $SESSION_NAME + lttng enable-event -u libcamera:\* + lttng start + # run libcamera application + lttng stop + lttng view + lttng destroy $SESSION_NAME + +See the `lttng documentation <https://lttng.org/docs/>`_ for further details. + +Analyzing a trace +----------------- + +As mentioned above, while an lttng tracing session exists and the trace is not +running, the trace output can be viewed as text by ``lttng view``. + +The trace log can also be viewed as text using babeltrace2. See the +`lttng trace analysis documentation +<https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt>`_ +for further details. + +babeltrace2 also has a C API and python bindings that can be used to process +traces. See the +`lttng python bindings documentation <https://babeltrace.org/docs/v2.0/python/bt2/>`_ +and the +`lttng C API documentation <https://babeltrace.org/docs/v2.0/libbabeltrace2/>`_ +for more details. + +As an example, there is a script ``utils/tracepoints/analyze-ipa-trace.py`` +that gathers statistics for the time taken for an IPA function call, by +measuring the time difference between pairs of events +``libcamera:ipa_call_start`` and ``libcamera:ipa_call_finish``. diff --git a/Documentation/index.rst b/Documentation/index.rst index a30688ac..ff697d4f 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -16,3 +16,4 @@ Developer Guide <guides/introduction> Application Writer's Guide <guides/application-developer> Pipeline Handler Writer's Guide <guides/pipeline-handler> + Tracing guide <guides/tracing> diff --git a/Documentation/meson.build b/Documentation/meson.build index d3d64f71..26a12fcd 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -56,6 +56,7 @@ if sphinx.found() 'guides/introduction.rst', 'guides/application-developer.rst', 'guides/pipeline-handler.rst', + 'guides/tracing.rst', ] release = 'release=v' + libcamera_git_version |