From patchwork Wed Oct 28 10:31:51 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 10292 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 23320BDB1E for ; Wed, 28 Oct 2020 10:32:14 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E2162625EF; Wed, 28 Oct 2020 11:32:13 +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="m49K5NSn"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B743D622AA for ; Wed, 28 Oct 2020 11:32:11 +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 38B0199A; Wed, 28 Oct 2020 11:32:09 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1603881131; bh=+838Y5Lx+BBccpV3d352tfg42yj5PqS21elx1n5dEK4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=m49K5NSneDk3dtLn7s2l6wUFN4CK1ZbqUvjdVYgxXpqcRRFhX7JMc4vzpN9Bypuik pGJXqCulrFy9HN47C6Yi7k33QBGM+FvquFsVZ5EApTeHrDNsuv8UQnEXvHpaqK2r74 Pf9cDSXb57oXyDZpW+y30l+38bnU4XPv7013I+Qg= From: Paul Elder To: libcamera-devel@lists.libcamera.org Date: Wed, 28 Oct 2020 19:31:51 +0900 Message-Id: <20201028103151.34575-6-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20201028103151.34575-1-paul.elder@ideasonboard.com> References: <20201028103151.34575-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 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 --- New in v2 --- Documentation/guides/tracing.rst | 127 +++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + Documentation/meson.build | 1 + 3 files changed, 129 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..31d4ff6e --- /dev/null +++ b/Documentation/guides/tracing.rst @@ -0,0 +1,127 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Tracing Guide +============= + +Guide to tracing in libcamera. + +Profiling vs Tracing +-------------------- + +Profiling is sampling at periodic points in time. This can be done with other +tools such as callgrind, perf, gprof, etc., without modification to the +application. + +Tracing is recording timestamps at specific locations. libcamera provides a +tracing facility. This guide shows how to use this tracing facility. + +Compiling +--------- + +To compile libcamera with tracing support, it must be enabled in meson, with +``-Dtracepoints=enabled``. It depends on ``liblttng-ust-dev`` (for Debian-based +distros). By default this build configuration option 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 is not necessary, +and you may simply begin with ``TRACEPOINT_EVENT`` (or similar). + +All tracepoint providers shall be ``libcamera``. According to lttng, the +tracepoint provider shold 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 a Request object. + +Tracepoint arguments may take C++ objects pointers, in which case the usual +C++ namespacing rules apply. The header that contains the necessary class +definitions should be ``#include`` ed as well. + +Note: the final parameter in ``TP_ARGS`` *must not* have a trailing comma, and +the parametsrs to ``TP_FIELDS`` are *space-separated*. Not following these will +cause compiler 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. + +The tracepoint provider name, as declared in the tracepoint definition, is not +included in the parameters of the tracepoint. + +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 obtained by ``lttng view``. + +babeltrace2 can also be used to view the trace log as text output. See the +`lttng 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 +searches the trace for pairs of events ``libcamera:ipa_call_start`` and +``libcamera:ipa_call_finish``, and gathers statistics on the time interval +between these pairs of these events, grouped by function name. In other words, +this script gathers statistics for the time taken for an IPA function call +(with the tracepoints inserted in the appropriate places). 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