From patchwork Thu Oct 29 10:16:29 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 10302 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id D92F7BDB9B for ; Thu, 29 Oct 2020 10:16:53 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id A643A628CE; Thu, 29 Oct 2020 11:16:53 +0100 (CET) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="jP5WCARN"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id CADD362053 for ; Thu, 29 Oct 2020 11:16:51 +0100 (CET) Received: from pyrite.rasen.tech (unknown [IPv6:2400:4051:61:600:2c71:1b79:d06d:5032]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 5A598576; Thu, 29 Oct 2020 11:16:50 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1603966611; bh=7WEBy7EFgLRC53y9bbenLESDUZD1JGsest6VoxhBnPY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jP5WCARNS4wzSmq3LQxI7ZYbZFwkQsdbJBOmczwKMBPpyPgB3wodrUiV0NjoAaIKi eXnmv7DwGbkDZnWnVddzhhCJQPqwoeWwWrS8BTH+XHbmb5/rI6nVzdzWAqJOFTWI2k tYTJ9vx0yxj4sOvDGNaaTT9cuhdptcXIx1epTr9k= From: Paul Elder To: libcamera-devel@lists.libcamera.org Date: Thu, 29 Oct 2020 19:16:29 +0900 Message-Id: <20201029101629.61798-7-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20201029101629.61798-1-paul.elder@ideasonboard.com> References: <20201029101629.61798-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 6/6] Documentation: tracing: Add tracing guide X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Add guide for tracepoints, including how to define and use them. Signed-off-by: Paul Elder Reviewed-by: Laurent Pinchart --- Changes in v3: - fix compilation error - reword english - add stuff about the new IPA call tracepoint macros New in v2 --- Documentation/guides/tracing.rst | 140 +++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + Documentation/meson.build | 1 + 3 files changed, 142 insertions(+) create mode 100644 Documentation/guides/tracing.rst diff --git a/Documentation/guides/tracing.rst b/Documentation/guides/tracing.rst new file mode 100644 index 00000000..8c59e7ed --- /dev/null +++ b/Documentation/guides/tracing.rst @@ -0,0 +1,140 @@ +.. 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 +-------------------- + +The first of two steps to using tracepoints is to define the 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, a tracepoints file for the Request object +would be 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 +`_. 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, +respecively. 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 `_. + +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 `_ 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 viewd as text by ``lttng view``. + +The trace log can also be viewed as text using babeltrace2. See the +`lttng trace analysis documentation `_ +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 `_ +and the +`lttng C API documentation `_ +for more details. + +As an example, there is a script ``utils/tracepoints/analyze.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 173c326f..8bc8922e 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -17,3 +17,4 @@ Application Writer's Guide Pipeline Handler Writer's Guide IPA Writer's guide + Tracing guide diff --git a/Documentation/meson.build b/Documentation/meson.build index f2300dac..17f3b9d7 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -55,6 +55,7 @@ if sphinx.found() 'guides/ipa.rst', 'guides/application-developer.rst', 'guides/pipeline-handler.rst', + 'guides/tracing.rst', ] release = 'release=v' + libcamera_git_version