Patch Detail
Show a patch.
GET /api/patches/10310/?format=api
{ "id": 10310, "url": "https://patchwork.libcamera.org/api/patches/10310/?format=api", "web_url": "https://patchwork.libcamera.org/patch/10310/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20201030085756.79329-6-paul.elder@ideasonboard.com>", "date": "2020-10-30T08:57:56", "name": "[libcamera-devel,v4,5/5] Documentation: tracing: Add tracing guide", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "d7c2685202b7bda1cac54a25784c7ed2e3e043f2", "submitter": { "id": 17, "url": "https://patchwork.libcamera.org/api/people/17/?format=api", "name": "Paul Elder", "email": "paul.elder@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/10310/mbox/", "series": [ { "id": 1435, "url": "https://patchwork.libcamera.org/api/series/1435/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=1435", "date": "2020-10-30T08:57:51", "name": "Tracing", "version": 4, "mbox": "https://patchwork.libcamera.org/series/1435/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/10310/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/10310/checks/", "tags": {}, "headers": { "Return-Path": "<libcamera-devel-bounces@lists.libcamera.org>", "X-Original-To": "parsemail@patchwork.libcamera.org", "Delivered-To": "parsemail@patchwork.libcamera.org", "Received": [ "from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 26C09BDB1E\n\tfor <parsemail@patchwork.libcamera.org>;\n\tFri, 30 Oct 2020 08:58:17 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id E886162979;\n\tFri, 30 Oct 2020 09:58:16 +0100 (CET)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 084CF628A5\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 30 Oct 2020 09:58:15 +0100 (CET)", "from pyrite.rasen.tech (unknown\n\t[IPv6:2400:4051:61:600:2c71:1b79:d06d:5032])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 3C68F9B7;\n\tFri, 30 Oct 2020 09:58:12 +0100 (CET)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"RJX1PfR0\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1604048294;\n\tbh=2kOoaciY+HnAFQ6qs4Pfm49M1NlG3j95wVFQF3CtmhQ=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=RJX1PfR0uE9bw0dPIhzvmXeGrov/ym2dRlhZy9Bdxf6/+1pG6kb9HKQmau1RK8ATt\n\tmKN2bJZZnv/Td2/VtnlXmxXuRqqn9I596l6+2HS24S8w0QyEOB2IaS0QvHCwNpKQ04\n\tEADI+5pu0Y2np+YbUOChdEOlD6JYkPB6zO10i2DA=", "From": "Paul Elder <paul.elder@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Fri, 30 Oct 2020 17:57:56 +0900", "Message-Id": "<20201030085756.79329-6-paul.elder@ideasonboard.com>", "X-Mailer": "git-send-email 2.27.0", "In-Reply-To": "<20201030085756.79329-1-paul.elder@ideasonboard.com>", "References": "<20201030085756.79329-1-paul.elder@ideasonboard.com>", "MIME-Version": "1.0", "Subject": "[libcamera-devel] [PATCH v4 5/5] Documentation: tracing: Add\n\ttracing guide", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Content-Type": "text/plain; charset=\"us-ascii\"", "Content-Transfer-Encoding": "7bit", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "Add guide for tracepoints, including how to define and use them.\n\nSigned-off-by: Paul Elder <paul.elder@ideasonboard.com>\nReviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n\n---\nChanges in v4:\n- fix spelling and some indentation\n- rebase on master instead of ipc\n\nChanges in v3:\n- fix compilation error\n- reword english\n- add stuff about the new IPA call tracepoint macros\n\nNew in v2\n---\n Documentation/guides/tracing.rst | 141 +++++++++++++++++++++++++++++++\n Documentation/index.rst | 1 +\n Documentation/meson.build | 1 +\n 3 files changed, 143 insertions(+)\n create mode 100644 Documentation/guides/tracing.rst", "diff": "diff --git a/Documentation/guides/tracing.rst b/Documentation/guides/tracing.rst\nnew file mode 100644\nindex 00000000..9c688b93\n--- /dev/null\n+++ b/Documentation/guides/tracing.rst\n@@ -0,0 +1,141 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+Tracing Guide\n+=============\n+\n+Guide to tracing in libcamera.\n+\n+Profiling vs Tracing\n+--------------------\n+\n+Tracing is recording timestamps at specific locations. libcamera provides a\n+tracing facility. This guide shows how to use this tracing facility.\n+\n+Tracing should not be confused with profiling, which samples execution\n+at periodic points in time. This can be done with other tools such as\n+callgrind, perf, gprof, etc., without modification to the application,\n+and is out of scope for this guide.\n+\n+Compiling\n+---------\n+\n+To compile libcamera with tracing support, it must be enabled through the\n+meson ``tracing`` option. It depends on the lttng-ust library (available in the\n+``liblttng-ust-dev`` package for Debian-based distributions).\n+By default the tracing option in meson is set to ``auto``, so if\n+liblttng is detected, it will be enabled by default. Conversely, if the option\n+is set to disabled, then libcamera will be compiled without tracing support.\n+\n+Defining tracepoints\n+--------------------\n+\n+libcamera already contains a set of tracepoints. To define additional\n+tracepoints, create a file\n+``include/libcamera/internal/tracepoints/{file}.tp``, where ``file`` is a\n+reasonable name related to the category of tracepoints that you wish to\n+define. For example, the tracepoints file for the Request object is called\n+``request.tp``. An entry for this file must be added in\n+``include/libcamera/internal/tracepoints/meson.build``.\n+\n+In this tracepoints file, define your tracepoints `as mandated by lttng\n+<https://lttng.org/man/3/lttng-ust>`_. The header boilerplate must *not* be\n+included (as it will conflict with the rest of our infrastructure), and\n+only the tracepoint definitions (with the ``TRACEPOINT_*`` macros) should be\n+included.\n+\n+All tracepoint providers shall be ``libcamera``. According to lttng, the\n+tracepoint provider should be per-project; this is the rationale for this\n+decision. To group tracepoint events, we recommend using\n+``{class_name}_{tracepoint_name}``, for example, ``request_construct`` for a\n+tracepoint for the constructor of the Request class.\n+\n+Tracepoint arguments may take C++ objects pointers, in which case the usual\n+C++ namespacing rules apply. The header that contains the necessary class\n+definitions must be included at the top of the tracepoint provider file.\n+\n+Note: the final parameter in ``TP_ARGS`` *must not* have a trailing comma, and\n+the parameters to ``TP_FIELDS`` are *space-separated*. Not following these will\n+cause compilation errors.\n+\n+Using tracepoints (in libcamera)\n+--------------------------------\n+\n+To use tracepoints in libcamera, first the header needs to be included:\n+\n+``#include \"libcamera/internal/tracepoints.h\"``\n+\n+Then to use the tracepoint:\n+\n+``LIBCAMERA_TRACEPOINT({tracepoint_event}, args...)``\n+\n+This macro must be used, as opposed to lttng's macros directly, because\n+lttng is an optional dependency of libcamera, so the code must compile and run\n+even when lttng is not present or when tracing is disabled.\n+\n+The tracepoint provider name, as declared in the tracepoint definition, is not\n+included in the parameters of the tracepoint.\n+\n+There are also two special tracepoints available for tracing IPA calls:\n+\n+``LIBCAMERA_TRACEPOINT_IPA_BEGIN({pipeline_name}, {ipa_function})``\n+\n+``LIBCAMERA_TRACEPOINT_IPA_END({pipeline_name}, {ipa_function})``\n+\n+These shall be placed where an IPA function is called from the pipeline handler,\n+and when the pipeline handler receives the corresponding response from the IPA,\n+respectively. These are the tracepoints that our sample analysis script\n+(see \"Analyzing a trace\") scans for when computing statistics on IPA call time.\n+\n+Using tracepoints (from an application)\n+---------------------------------------\n+\n+As applications are not part of libcamera, but rather users of libcamera,\n+applications should seek their own tracing mechanisms. For ease of tracing\n+the application alongside tracing libcamera, it is recommended to also\n+`use lttng <https://lttng.org/docs/#doc-tracing-your-own-user-application>`_.\n+\n+Using tracepoints (from closed-source IPA)\n+------------------------------------------\n+\n+Similar to applications, closed-source IPAs can simply use lttng on their own,\n+or any other tracing mechanism if desired.\n+\n+Collecting a trace\n+------------------\n+\n+A trace can be collected fairly simply from lttng:\n+\n+.. code-block:: bash\n+\n+ lttng create $SESSION_NAME\n+ lttng enable-event -u libcamera:\\*\n+ lttng start\n+ # run libcamera application\n+ lttng stop\n+ lttng view\n+ lttng destroy $SESSION_NAME\n+\n+See the `lttng documentation <https://lttng.org/docs/>`_ for further details.\n+\n+Analyzing a trace\n+-----------------\n+\n+As mentioned above, while an lttng tracing session exists and the trace is not\n+running, the trace output can be viewed as text by ``lttng view``.\n+\n+The trace log can also be viewed as text using babeltrace2. See the\n+`lttng trace analysis documentation\n+<https://lttng.org/docs/#doc-viewing-and-analyzing-your-traces-bt>`_\n+for further details.\n+\n+babeltrace2 also has a C API and python bindings that can be used to process\n+traces. See the\n+`lttng python bindings documentation <https://babeltrace.org/docs/v2.0/python/bt2/>`_\n+and the\n+`lttng C API documentation <https://babeltrace.org/docs/v2.0/libbabeltrace2/>`_\n+for more details.\n+\n+As an example, there is a script ``utils/tracepoints/analyze-ipa-trace.py``\n+that gathers statistics for the time taken for an IPA function call, by\n+measuring the time difference between pairs of events\n+``libcamera:ipa_call_start`` and ``libcamera:ipa_call_finish``.\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex a30688ac..ff697d4f 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -16,3 +16,4 @@\n Developer Guide <guides/introduction>\n Application Writer's Guide <guides/application-developer>\n Pipeline Handler Writer's Guide <guides/pipeline-handler>\n+ Tracing guide <guides/tracing>\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex d3d64f71..26a12fcd 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -56,6 +56,7 @@ if sphinx.found()\n 'guides/introduction.rst',\n 'guides/application-developer.rst',\n 'guides/pipeline-handler.rst',\n+ 'guides/tracing.rst',\n ]\n \n release = 'release=v' + libcamera_git_version\n", "prefixes": [ "libcamera-devel", "v4", "5/5" ] }