Patch Detail
Show a patch.
GET /api/patches/10302/?format=api
{ "id": 10302, "url": "https://patchwork.libcamera.org/api/patches/10302/?format=api", "web_url": "https://patchwork.libcamera.org/patch/10302/", "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": "<20201029101629.61798-7-paul.elder@ideasonboard.com>", "date": "2020-10-29T10:16:29", "name": "[libcamera-devel,v3,6/6] Documentation: tracing: Add tracing guide", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "534e24d75b92225de3d3ef719204482936d41084", "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/10302/mbox/", "series": [ { "id": 1432, "url": "https://patchwork.libcamera.org/api/series/1432/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=1432", "date": "2020-10-29T10:16:23", "name": "Tracing", "version": 3, "mbox": "https://patchwork.libcamera.org/series/1432/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/10302/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/10302/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 D92F7BDB9B\n\tfor <parsemail@patchwork.libcamera.org>;\n\tThu, 29 Oct 2020 10:16:53 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id A643A628CE;\n\tThu, 29 Oct 2020 11:16:53 +0100 (CET)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id CADD362053\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 29 Oct 2020 11:16:51 +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 5A598576;\n\tThu, 29 Oct 2020 11:16:50 +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=\"jP5WCARN\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1603966611;\n\tbh=7WEBy7EFgLRC53y9bbenLESDUZD1JGsest6VoxhBnPY=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=jP5WCARNS4wzSmq3LQxI7ZYbZFwkQsdbJBOmczwKMBPpyPgB3wodrUiV0NjoAaIKi\n\teXnmv7DwGbkDZnWnVddzhhCJQPqwoeWwWrS8BTH+XHbmb5/rI6nVzdzWAqJOFTWI2k\n\ttYTJ9vx0yxj4sOvDGNaaTT9cuhdptcXIx1epTr9k=", "From": "Paul Elder <paul.elder@ideasonboard.com>", "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\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>\n\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 | 140 +++++++++++++++++++++++++++++++\n Documentation/index.rst | 1 +\n Documentation/meson.build | 1 +\n 3 files changed, 142 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..8c59e7ed\n--- /dev/null\n+++ b/Documentation/guides/tracing.rst\n@@ -0,0 +1,140 @@\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+The first of two steps to using tracepoints is to define the tracepoints.\n+\n+Create a file ``include/libcamera/internal/tracepoints/{file}.tp``, where\n+``file`` is a reasonable name related to the category of tracepoints that\n+you wish to define. For example, a tracepoints file for the Request object\n+would be called ``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+respecively. 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 viewd 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 <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.py`` that gathers\n+statistics for the time taken for an IPA function call, by measuring the time\n+difference between pairs of events ``libcamera:ipa_call_start`` and\n+``libcamera:ipa_call_finish``.\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex 173c326f..8bc8922e 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -17,3 +17,4 @@\n Application Writer's Guide <guides/application-developer>\n Pipeline Handler Writer's Guide <guides/pipeline-handler>\n IPA Writer's guide <guides/ipa>\n+ Tracing guide <guides/tracing>\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex f2300dac..17f3b9d7 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -55,6 +55,7 @@ if sphinx.found()\n 'guides/ipa.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", "v3", "6/6" ] }