From patchwork Wed Aug 7 15:44:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20823 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 CF191C323E for ; Wed, 7 Aug 2024 15:44:37 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 7F737633B3; Wed, 7 Aug 2024 17:44:37 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="id63i8Yy"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id E59D963394 for ; Wed, 7 Aug 2024 17:44:34 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id C41666AF; Wed, 7 Aug 2024 17:43:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723045422; bh=tkU0SmKTvcKZCDJur3Yv2G1MUT+pCWPVAma3TwrKoT0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=id63i8YyRt/np5Aolj4g/S7VCldRIOsSusQC7Naab4XrKuIJ3Y5YqKjSxko4B1Lfm ofgG3zQ9+eHQW/FVhGwKuX9Ee4A0iJQSQI4HnlS8B3RKirc9TOXzek9sMUNn/PND59 r+VLdqOuvqrcupndjAgIINFrczdDWlZKL9KWQPaI= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v6 1/5] Documentation: Add Thread safety page Date: Wed, 7 Aug 2024 18:44:06 +0300 Message-ID: <20240807154410.9552-2-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> References: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 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" From: Daniel Scally Move the section of the Thread support page dealing with thread safety to a dedicated .dox file at Documentation/. This is done to support the splitting of the Documentation into a public and internal version. With a separate page, references can be made to thread safety without having to include the Thread class in the doxygen run. Signed-off-by: Daniel Scally --- Changes since v5: - Much of the content that dealt with internal implementation was moved back to its place against the Thread class. The thread safety section is retained in a separate page, with a single reference to the main thread support page who's display is conditional on the doxygen INTERNAL_DOCS directive. Given the scope of the changes, I dropped the R-b tags the patch had accumulated Changes since v1: - New patch --- Documentation/Doxyfile.in | 4 +++- Documentation/thread-safety.dox | 40 +++++++++++++++++++++++++++++++++ src/libcamera/base/thread.cpp | 36 ----------------------------- 3 files changed, 43 insertions(+), 37 deletions(-) create mode 100644 Documentation/thread-safety.dox diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index 62e63968ce62..6e5a3830ec38 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -23,7 +23,8 @@ CASE_SENSE_NAMES = YES QUIET = YES WARN_AS_ERROR = @WARN_AS_ERROR@ -INPUT = "@TOP_SRCDIR@/include/libcamera" \ +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ "@TOP_SRCDIR@/src/ipa/ipu3" \ "@TOP_SRCDIR@/src/ipa/libipa" \ "@TOP_SRCDIR@/src/libcamera" \ @@ -32,6 +33,7 @@ INPUT = "@TOP_SRCDIR@/include/libcamera" \ FILE_PATTERNS = *.c \ *.cpp \ + *.dox \ *.h RECURSIVE = YES diff --git a/Documentation/thread-safety.dox b/Documentation/thread-safety.dox new file mode 100644 index 000000000000..d1f8bd37e082 --- /dev/null +++ b/Documentation/thread-safety.dox @@ -0,0 +1,40 @@ +/** + * \page thread-safety Reentrancy and Thread-Safety + * + * Through the documentation, several terms are used to define how classes and + * their member functions can be used from multiple threads. + * + * - A **reentrant** function may be called simultaneously from multiple + * threads if and only if each invocation uses a different instance of the + * class. This is the default for all member functions not explictly marked + * otherwise. + * + * - \anchor thread-safe A **thread-safe** function may be called + * simultaneously from multiple threads on the same instance of a class. A + * thread-safe function is thus reentrant. Thread-safe functions may also be + * called simultaneously with any other reentrant function of the same class + * on the same instance. + * + * - \anchor thread-bound A **thread-bound** function may be called only from + * the thread that the class instances lives in. A thread-bound function is + * not thread-safe, and may or may not be reentrant. + * + * \internal + * For more information on the implementation of thread-bound functions, see + * section \ref thread-objects. + * \endinternal + * + * Neither reentrancy nor thread-safety, in this context, mean that a function + * may be called simultaneously from the same thread, for instance from a + * callback invoked by the function. This may deadlock and isn't allowed unless + * separately documented. + * + * A class is defined as reentrant, thread-safe or thread-bound if all its + * member functions are reentrant, thread-safe or thread-bound respectively. + * Some member functions may additionally be documented as having additional + * thread-related attributes. + * + * Most classes are reentrant but not thread-safe, as making them fully + * thread-safe would incur locking costs considered prohibitive for the + * expected use cases. + */ diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp index 72733431a22e..8735670b8a1e 100644 --- a/src/libcamera/base/thread.cpp +++ b/src/libcamera/base/thread.cpp @@ -64,42 +64,6 @@ * receiver's event loop, running in the receiver's thread. This mechanism can * be overridden by selecting a different connection type when calling * Signal::connect(). - * - * \section thread-reentrancy Reentrancy and Thread-Safety - * - * Through the documentation, several terms are used to define how classes and - * their member functions can be used from multiple threads. - * - * - A **reentrant** function may be called simultaneously from multiple - * threads if and only if each invocation uses a different instance of the - * class. This is the default for all member functions not explictly marked - * otherwise. - * - * - \anchor thread-safe A **thread-safe** function may be called - * simultaneously from multiple threads on the same instance of a class. A - * thread-safe function is thus reentrant. Thread-safe functions may also be - * called simultaneously with any other reentrant function of the same class - * on the same instance. - * - * - \anchor thread-bound A **thread-bound** function may be called only from - * the thread that the class instances lives in (see section \ref - * thread-objects). For instances of classes that do not derive from the - * Object class, this is the thread in which the instance was created. A - * thread-bound function is not thread-safe, and may or may not be reentrant. - * - * Neither reentrancy nor thread-safety, in this context, mean that a function - * may be called simultaneously from the same thread, for instance from a - * callback invoked by the function. This may deadlock and isn't allowed unless - * separately documented. - * - * A class is defined as reentrant, thread-safe or thread-bound if all its - * member functions are reentrant, thread-safe or thread-bound respectively. - * Some member functions may additionally be documented as having additional - * thread-related attributes. - * - * Most classes are reentrant but not thread-safe, as making them fully - * thread-safe would incur locking costs considered prohibitive for the - * expected use cases. */ /** From patchwork Wed Aug 7 15:44:07 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20824 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 F36B3C323E for ; Wed, 7 Aug 2024 15:44:39 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id CE39A6338D; Wed, 7 Aug 2024 17:44:38 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="aObsxNtq"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 2446E6337E for ; Wed, 7 Aug 2024 17:44:36 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 2ECE16AF for ; Wed, 7 Aug 2024 17:43:43 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723045423; bh=ck5vQy6D5m5M5mnVpqjWjYE0aAFq9EhX1huaWt55/q8=; h=From:To:Subject:Date:In-Reply-To:References:From; b=aObsxNtqyFx7T2BvKLtdDC970gOyFoV4o6yNx4Np10GCUKfziL+PxH5sVzvKOp8ZA XBcjX5vtKXHhYxiIa5CRORgNlWoqCWKS2op5c8NXbGWKPLW1Dn3svICtZMs2nlfJcQ k9DSkLdOOv2DjnNskBc+Kjx4ulG6XSIWgyUWBX9M= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v6 2/5] Documentation: Split doxygen_input in public and internal inputs Date: Wed, 7 Aug 2024 18:44:07 +0300 Message-ID: <20240807154410.9552-3-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> References: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 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" To prepare for splitting the API documentation in public and internal documents, split the doxygen_input list in the public and internal counterparts. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- Documentation/meson.build | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index 070420715bd1..1d84ed815b50 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -28,27 +28,34 @@ if doxygen.found() and dot.found() output : 'Doxyfile', configuration : cdata) - doxygen_input = [ - doxyfile, - libcamera_base_headers, + doxygen_public_input = [ + libcamera_base_public_headers, libcamera_base_public_sources, - libcamera_base_internal_sources, - libcamera_internal_headers, - libcamera_ipa_headers, - libcamera_ipa_interfaces, libcamera_public_headers, libcamera_public_sources, + ] + + doxygen_internal_input = [ + libcamera_base_private_headers, + libcamera_base_internal_sources, + libcamera_internal_headers, libcamera_internal_sources, + libcamera_ipa_headers, + libcamera_ipa_interfaces, libipa_headers, libipa_sources, ] if is_variable('ipu3_ipa_sources') - doxygen_input += [ipu3_ipa_sources] + doxygen_internal_input += [ipu3_ipa_sources] endif custom_target('doxygen', - input : doxygen_input, + input : [ + doxyfile, + doxygen_public_input, + doxygen_internal_input, + ], output : 'api-html', command : [doxygen, doxyfile], install : true, From patchwork Wed Aug 7 15:44:08 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20825 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 431ACC323E for ; Wed, 7 Aug 2024 15:44:42 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 034EA633BA; Wed, 7 Aug 2024 17:44:42 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="J3fhogfe"; 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 940C9633B4 for ; Wed, 7 Aug 2024 17:44:37 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 962A16AF; Wed, 7 Aug 2024 17:43:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723045424; bh=1e2xS2Vz82SAbaRCpKPNmXCkQoVtnK0YgMwwTSZwrQk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=J3fhogfewbHDRzrALkiI6J++UT+kqFmcmnt/s0H6/fiwE2EXn1wXEa5Yvl4YeW2iC Z7yxlnvmQpgagERFQZbZXzJhBp7rNgJP7KLOp5GIgH30NQoetOlxmyPKO0b0/UlRkk 4gFhFAuVSRkM90K3DwtBQONmO95oNJ/LRrnxefz8= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v6 3/5] Documentation: Split public/private documentation Date: Wed, 7 Aug 2024 18:44:08 +0300 Message-ID: <20240807154410.9552-4-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> References: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 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" From: Daniel Scally The API reference pages generated by Doxygen are comprehensive, but therefore quite overwhelming for application developers who will likely never need to use the majority of the library's objects. To reduce the complexity of the documentation, split it into two runs of doxygen. The first run of doxygen is for the public API. We pass a specific list of source files to parse, which is built from the arrays of public headers and sources in meson build files. This ensures that we only generate the documentation for code from those files. A custom Python script is needed to add the list of input files to Doxyfile, as several of the objects included in the header and source array are custom_tgt objects, which can't be handled as strings to populate a variable in the configuration data. The headers defining the Extensible and Object classes (class.h and object.h respectively), as well as the corresponding source files, are excluded from the public API documentation despite being referenced in the meson public headers and sources arrays. This is due to the fact that public API classes inherit from Extensible and Object, making the Extensible and Object classes part of the public ABI. Those two base classes are however implementation details and must not be accessed directly by application code. The second run of doxygen is for the internal API. This contains documentation for all of the library's objects as it currently does. This set will now be output into build/Documentation/internal-api-html. Signed-off-by: Daniel Scally Co-developed-by: Laurent Pinchart Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Daniel Scally --- Changes since v5: - Reword and fix comments documenting the doxygen process - Drop the gen-doxyfile.py step for the internal doc - Drop unneeded comment - Add blank line --- .../{Doxyfile.in => Doxyfile-common.in} | 24 -------- Documentation/Doxyfile-internal.in | 30 +++++++++ Documentation/Doxyfile-public.in | 20 ++++++ Documentation/gen-doxyfile.py | 46 ++++++++++++++ Documentation/meson.build | 61 +++++++++++++++++-- 5 files changed, 151 insertions(+), 30 deletions(-) rename Documentation/{Doxyfile.in => Doxyfile-common.in} (62%) create mode 100644 Documentation/Doxyfile-internal.in create mode 100644 Documentation/Doxyfile-public.in create mode 100755 Documentation/gen-doxyfile.py diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile-common.in similarity index 62% rename from Documentation/Doxyfile.in rename to Documentation/Doxyfile-common.in index 6e5a3830ec38..a70aee430e77 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile-common.in @@ -17,20 +17,11 @@ EXTENSION_MAPPING = h=C++ TOC_INCLUDE_HEADINGS = 0 -INTERNAL_DOCS = YES CASE_SENSE_NAMES = YES QUIET = YES WARN_AS_ERROR = @WARN_AS_ERROR@ -INPUT = "@TOP_SRCDIR@/Documentation" \ - "@TOP_SRCDIR@/include/libcamera" \ - "@TOP_SRCDIR@/src/ipa/ipu3" \ - "@TOP_SRCDIR@/src/ipa/libipa" \ - "@TOP_SRCDIR@/src/libcamera" \ - "@TOP_BUILDDIR@/include/libcamera" \ - "@TOP_BUILDDIR@/src/libcamera" - FILE_PATTERNS = *.c \ *.cpp \ *.dox \ @@ -38,19 +29,6 @@ FILE_PATTERNS = *.c \ RECURSIVE = YES -EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ - @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ - @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ - @TOP_SRCDIR@/src/libcamera/pipeline/ \ - @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ - @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ - @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \ - @TOP_BUILDDIR@/src/libcamera/proxy/ - EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \ @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \ @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \ @@ -73,8 +51,6 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \ EXCLUDE_SYMLINKS = YES -HTML_OUTPUT = api-html - GENERATE_LATEX = NO MACRO_EXPANSION = YES diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in new file mode 100644 index 000000000000..5e0310091416 --- /dev/null +++ b/Documentation/Doxyfile-internal.in @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation +@INCLUDE = Doxyfile-common + +HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_MEMBERS = NO +HTML_OUTPUT = internal-api-html +INTERNAL_DOCS = YES + +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ + "@TOP_SRCDIR@/src/ipa/ipu3" \ + "@TOP_SRCDIR@/src/ipa/libipa" \ + "@TOP_SRCDIR@/src/libcamera" \ + "@TOP_BUILDDIR@/include/libcamera" \ + "@TOP_BUILDDIR@/src/libcamera" + +EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ + @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ + @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ + @TOP_SRCDIR@/src/libcamera/pipeline/ \ + @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ + @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \ + @TOP_BUILDDIR@/src/libcamera/proxy/ diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in new file mode 100644 index 000000000000..36bb57584a07 --- /dev/null +++ b/Documentation/Doxyfile-public.in @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation +@INCLUDE = Doxyfile-common + +HIDE_UNDOC_CLASSES = YES +HIDE_UNDOC_MEMBERS = YES +HTML_OUTPUT = api-html +INTERNAL_DOCS = NO + +INPUT = "@TOP_SRCDIR@/Documentation" \ + ${inputs} + +EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/class.h \ + @TOP_SRCDIR@/include/libcamera/base/object.h \ + @TOP_SRCDIR@/include/libcamera/base/span.h \ + @TOP_SRCDIR@/src/libcamera/base/class.cpp \ + @TOP_SRCDIR@/src/libcamera/base/object.cpp + +PREDEFINED += __DOXYGEN_PUBLIC__ diff --git a/Documentation/gen-doxyfile.py b/Documentation/gen-doxyfile.py new file mode 100755 index 000000000000..c265bc2f3fc4 --- /dev/null +++ b/Documentation/gen-doxyfile.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (C) 2024, Google Inc. +# +# Author: Laurent Pinchart +# +# Generate Doxyfile from a template + +import argparse +import os +import string +import sys + + +def fill_template(template, data): + + template = open(template, 'rb').read() + template = template.decode('utf-8') + template = string.Template(template) + + return template.substitute(data) + + +def main(argv): + + parser = argparse.ArgumentParser() + parser.add_argument('-o', dest='output', metavar='file', + type=argparse.FileType('w', encoding='utf-8'), + default=sys.stdout, + help='Output file name (default: standard output)') + parser.add_argument('template', metavar='doxyfile.tmpl', type=str, + help='Doxyfile template') + parser.add_argument('inputs', type=str, nargs='*', + help='Input files') + + args = parser.parse_args(argv[1:]) + + inputs = [f'"{os.path.realpath(input)}"' for input in args.inputs] + data = fill_template(args.template, {'inputs': (' \\\n' + ' ' * 25).join(inputs)}) + args.output.write(data) + + return 0 + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/Documentation/meson.build b/Documentation/meson.build index 1d84ed815b50..1ba40fdf67ac 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -24,9 +24,9 @@ if doxygen.found() and dot.found() cdata.set('PREDEFINED', ' \\\n\t\t\t '.join(doxygen_predefined)) - doxyfile = configure_file(input : 'Doxyfile.in', - output : 'Doxyfile', - configuration : cdata) + doxyfile_common = configure_file(input : 'Doxyfile-common.in', + output : 'Doxyfile-common', + configuration : cdata) doxygen_public_input = [ libcamera_base_public_headers, @@ -50,17 +50,66 @@ if doxygen.found() and dot.found() doxygen_internal_input += [ipu3_ipa_sources] endif - custom_target('doxygen', + # We run doxygen twice - the first run excludes internal API objects as it + # is intended to document the public API only. A second run covers all of + # the library's objects for libcamera developers. Common configuration is + # set in an initially generated Doxyfile, which is then included by the two + # final Doxyfiles. + + # This is the "public" run of doxygen generating an abridged version of the + # API's documentation. + + doxyfile_tmpl = configure_file(input : 'Doxyfile-public.in', + output : 'Doxyfile-public.tmpl', + configuration : cdata) + + # The set of public input files stored in the doxygen_public_input array + # needs to be set in Doxyfile public. We can't pass them through cdata + # cdata, as some of the array members are custom_tgt instances, which + # configuration_data.set() doesn't support. Using a separate script invoked + # through custom_target(), which supports custom_tgt instances as inputs. + + doxyfile = custom_target('doxyfile-public', + input : [ + doxygen_public_input, + ], + output : 'Doxyfile-public', + command : [ + 'gen-doxyfile.py', + '-o', '@OUTPUT@', + doxyfile_tmpl, + '@INPUT@', + ]) + + custom_target('doxygen-public', input : [ doxyfile, - doxygen_public_input, - doxygen_internal_input, + doxyfile_common, ], output : 'api-html', command : [doxygen, doxyfile], install : true, install_dir : doc_install_dir, install_tag : 'doc') + + # This is the internal documentation, which hard-codes a list of directories + # to parse in its doxyfile. + + doxyfile = configure_file(input : 'Doxyfile-internal.in', + output : 'Doxyfile-internal', + configuration : cdata) + + custom_target('doxygen-internal', + input : [ + doxyfile, + doxyfile_common, + doxygen_internal_input, + ], + output : 'internal-api-html', + command : [doxygen, doxyfile], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc-internal') endif # From patchwork Wed Aug 7 15:44:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20826 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 DE01FC323E for ; Wed, 7 Aug 2024 15:44:43 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 7D7A9633BF; Wed, 7 Aug 2024 17:44:43 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="sc/N/sRy"; 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 0D35A633B9 for ; Wed, 7 Aug 2024 17:44:39 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 0A9926AF; Wed, 7 Aug 2024 17:43:45 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723045426; bh=JdX1wf465nKXe4Y64c6ARzhJaj1/TZdocqXuGhVqcEY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=sc/N/sRygTl3LZOmXTRNHhb3Bfh+QzXmefvc96kjeAuMq4zoxYUmZHsI+FwdbFoq8 ua7kXhdKma49FrxPrUelbF2u54C7avGwrvxNAZMDtLgk898EQ1pSuaFIlON6Kp2Bfy BoT5t5tPNWlQ6oOG2MMJ4MkGInZljFPo8Aq1+iuI= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v6 4/5] Documentation: Improve doxygen main page Date: Wed, 7 Aug 2024 18:44:09 +0300 Message-ID: <20240807154410.9552-5-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> References: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 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" From: Daniel Scally The "Main Page" of the doxygen generated API reference is currently totally empty. Expand it with some introductory text along with links to the developer's guide, application developer's guide and the pipeline and IPA module writer's guides. Provide an easy link to switch between the reduced public reference pages and the more complete internal ones. Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham Signed-off-by: Daniel Scally --- Documentation/Doxyfile-internal.in | 1 + Documentation/mainpage.dox | 33 ++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 Documentation/mainpage.dox diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in index 5e0310091416..e56321c3f8f6 100644 --- a/Documentation/Doxyfile-internal.in +++ b/Documentation/Doxyfile-internal.in @@ -3,6 +3,7 @@ @INCLUDE_PATH = @TOP_BUILDDIR@/Documentation @INCLUDE = Doxyfile-common +ENABLED_SECTIONS = internal HIDE_UNDOC_CLASSES = NO HIDE_UNDOC_MEMBERS = NO HTML_OUTPUT = internal-api-html diff --git a/Documentation/mainpage.dox b/Documentation/mainpage.dox new file mode 100644 index 000000000000..d5a57653ca93 --- /dev/null +++ b/Documentation/mainpage.dox @@ -0,0 +1,33 @@ +/** +\mainpage libcamera API reference + +Welcome to the API reference for libcamera, +a complex camera support library for Linux, Android and ChromeOS. These pages +are automatically generated from the libcamera source code and describe the API +in detail - if this is your first interaction with libcamera then you may find +it useful to visit the [developer's guide](../html/guides/introduction.html) in +the first instance, which can provide a more generic introduction to the +library's concepts. + +\if internal + +As a follow-on to the developer's guide, to assist you in adding support for +your platform the [pipeline handler writer's guide](../html/guides/pipeline-handler.html) +and the [ipa module writer's guide](../html/guides/ipa.html) should be helpful. + +The full libcamera API is documented here. If you wish to see only the public +part of the API you can use [these pages](../api-html/index.html) instead. + +\else + +As a follow-on to the developer's guide, to assist you in using libcamera within +your project the [application developer's guide](../html/guides/application-developer.html) +gives an overview on how to achieve that. + +Only the public part of the libcamera API is documented here; if you are a +developer seeking to add support for your hardware to the library or make other +improvements, you should switch to the internal API +[reference pages](../internal-api-html/index.html) instead. + +\endif +*/ From patchwork Wed Aug 7 15:44:10 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20827 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 CF163C324E for ; Wed, 7 Aug 2024 15:44:44 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 4823C633B9; Wed, 7 Aug 2024 17:44:44 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Z3jKQ+gb"; 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 6B63C633B1 for ; Wed, 7 Aug 2024 17:44:40 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 6367F6AF for ; Wed, 7 Aug 2024 17:43:47 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723045427; bh=SMVJVYTg2/cWna/e1QQyfKmIcnnBLU6FwQqAkJCpIHQ=; h=From:To:Subject:Date:In-Reply-To:References:From; b=Z3jKQ+gbEoZlYQfJLJRPflHAG8kEC2fXYM62UZmXtbcjOfgHwFO8agN8CUDwO8f66 SLJwDwnkmSC5S+oIFqjpOSj8XshqbldATtYX3HDH93iJcAMWYYuh+XEYwhJFqkxwwg IueBiSdOkf/ddOIkm6QFQki2k13+q9kY2ihcrAVw= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v6 5/5] libcamera: camera: Hide Camera::create() from the public API Date: Wed, 7 Aug 2024 18:44:10 +0300 Message-ID: <20240807154410.9552-6-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> References: <20240807154410.9552-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 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" The Camera::create() function is internal. Hide it from the public API documentation. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Daniel Scally --- src/libcamera/camera.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index aca466c9ba72..382a68f7bddd 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -821,6 +821,7 @@ void Camera::Private::setState(State state) */ /** + * \internal * \brief Create a camera instance * \param[in] d Camera private data * \param[in] id The ID of the camera device