From patchwork Mon Aug 5 14:36:37 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20787 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 9C775C323E for ; Mon, 5 Aug 2024 14:37:25 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 0434B63381; Mon, 5 Aug 2024 16:37:25 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="CMLtXdAG"; 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 6F9AC63369 for ; Mon, 5 Aug 2024 16:37:19 +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 5A2EB581 for ; Mon, 5 Aug 2024 16:36:27 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868587; bh=KMMIZCVjewT6AJyLgj1xUaFlWMm5lb2EMRfjtTBB5sM=; h=From:To:Subject:Date:In-Reply-To:References:From; b=CMLtXdAGQRcwOlD0ore+wwmL+PYqQUQkQrYiIAo0HMpDsKoCGmprQbZfihS60IW2Y S8k+FjvuzHwlhtYS8oWaIOMGH5O91+JLAEQ6nXF12t4rNGkODBMT/B1f7HVMYw0Byf HtkWqjzuI6W3U5o+yFijbDX5wITAP51Wbqj9oOFQ= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 01/18] libcamera: Drop path prefix from Doxygen file directive Date: Mon, 5 Aug 2024 17:36:37 +0300 Message-ID: <20240805143654.20870-2-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 Doxygen directive only requires qualifying header file names with a path to differentiate between multiple header files with the same name. Most file directives that refer to unambiguous files do not have a libcamera/ and/or internal/ path prefix, but a few do, most likely due to copy&paste. Drop the prefix in those few files for consistency. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- src/libcamera/converter.cpp | 2 +- src/libcamera/converter/converter_v4l2_m2m.cpp | 2 +- src/libcamera/fence.cpp | 2 +- src/libcamera/mapped_framebuffer.cpp | 2 +- src/libcamera/orientation.cpp | 2 +- src/libcamera/yaml_parser.cpp | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libcamera/converter.cpp b/src/libcamera/converter.cpp index 2ab461332677..8237998f044b 100644 --- a/src/libcamera/converter.cpp +++ b/src/libcamera/converter.cpp @@ -14,7 +14,7 @@ #include "libcamera/internal/media_device.h" /** - * \file internal/converter.h + * \file converter.h * \brief Abstract converter */ diff --git a/src/libcamera/converter/converter_v4l2_m2m.cpp b/src/libcamera/converter/converter_v4l2_m2m.cpp index 2e77872e1710..006ba9f7f665 100644 --- a/src/libcamera/converter/converter_v4l2_m2m.cpp +++ b/src/libcamera/converter/converter_v4l2_m2m.cpp @@ -23,7 +23,7 @@ #include "libcamera/internal/v4l2_videodevice.h" /** - * \file internal/converter/converter_v4l2_m2m.h + * \file converter/converter_v4l2_m2m.h * \brief V4L2 M2M based converter */ diff --git a/src/libcamera/fence.cpp b/src/libcamera/fence.cpp index 634c74f8e13e..73299b402702 100644 --- a/src/libcamera/fence.cpp +++ b/src/libcamera/fence.cpp @@ -11,7 +11,7 @@ namespace libcamera { /** * - * \file libcamera/fence.h + * \file fence.h * \brief Definition of the Fence class */ diff --git a/src/libcamera/mapped_framebuffer.cpp b/src/libcamera/mapped_framebuffer.cpp index b3104e0504d4..ad82e1f6e49c 100644 --- a/src/libcamera/mapped_framebuffer.cpp +++ b/src/libcamera/mapped_framebuffer.cpp @@ -16,7 +16,7 @@ #include /** - * \file libcamera/internal/mapped_framebuffer.h + * \file mapped_framebuffer.h * \brief Frame buffer memory mapping support */ diff --git a/src/libcamera/orientation.cpp b/src/libcamera/orientation.cpp index 47fd6a32502b..fd191197fb8c 100644 --- a/src/libcamera/orientation.cpp +++ b/src/libcamera/orientation.cpp @@ -11,7 +11,7 @@ #include /** - * \file libcamera/orientation.h + * \file orientation.h * \brief Image orientation definition */ diff --git a/src/libcamera/yaml_parser.cpp b/src/libcamera/yaml_parser.cpp index 025006bcdcdd..8b6a403898be 100644 --- a/src/libcamera/yaml_parser.cpp +++ b/src/libcamera/yaml_parser.cpp @@ -18,7 +18,7 @@ #include /** - * \file libcamera/internal/yaml_parser.h + * \file yaml_parser.h * \brief A YAML parser helper */ From patchwork Mon Aug 5 14:36:38 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20788 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 C4E37C323E for ; Mon, 5 Aug 2024 14:37:28 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id F104A6338B; Mon, 5 Aug 2024 16:37:26 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="BHLCLnyj"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 5009C63381 for ; Mon, 5 Aug 2024 16:37:20 +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 B6C00581 for ; Mon, 5 Aug 2024 16:36:28 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868588; bh=3EZ88y47cKHOkONmkzjpxp1fS7sHbz3+QV7akuG3PyM=; h=From:To:Subject:Date:In-Reply-To:References:From; b=BHLCLnyjscVysdnIw1iBakmaJ9dGDmBGjRqaCoqicavCxv0zct+d/RXGhM2NAa23E 2kscjo2HgoncmJx0w5evhpjCmeYa6ZAO7ftUpqyZr74zUT4S9kxN7NWPIERrQhNa0x AaE5eOyzqp9Lxj1mDwv8aHO91GzHlPa87Tt9Iico= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 02/18] libcamera: Make all internal headers visible to Doxygen Date: Mon, 5 Aug 2024 17:36:38 +0300 Message-ID: <20240805143654.20870-3-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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" Two classes that have both public and internal headers, namely Camera and Request, make only their public header visible to Doxygen through a file directive. Fix them. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- src/libcamera/camera.cpp | 5 +++++ src/libcamera/request.cpp | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index 67f3490133b2..f89510ea0472 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -117,6 +117,11 @@ * of view is affected by the pipeline. */ +/** + * \file libcamera/internal/camera.h + * \brief Internal camera device handling + */ + namespace libcamera { LOG_DECLARE_CATEGORY(Camera) diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp index cfb451e908da..fdf12c1e9088 100644 --- a/src/libcamera/request.cpp +++ b/src/libcamera/request.cpp @@ -28,6 +28,11 @@ * \brief Describes a frame capture request to be processed by a camera */ +/** + * \file libcamera/internal/request.h + * \brief Internal support for request handling + */ + namespace libcamera { LOG_DEFINE_CATEGORY(Request) From patchwork Mon Aug 5 14:36:39 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20789 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 5BF4DC323E for ; Mon, 5 Aug 2024 14:37:31 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 59182633AC; Mon, 5 Aug 2024 16:37:29 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="LFyW8+Q7"; 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 AFB8463382 for ; Mon, 5 Aug 2024 16:37:21 +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 27F19A06 for ; Mon, 5 Aug 2024 16:36:30 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868590; bh=GMYP9+hc4wawf3lQq7gB+8Zftz8+lePBjw7ngzJlhIA=; h=From:To:Subject:Date:In-Reply-To:References:From; b=LFyW8+Q7ri0lp7UmShpU04iG5YLHHKrh9Sq/1aRfEUw1nJp/z47VpPedofyO8aAW9 P0gS8SRySMsg4oLO//WC83t1Hn0Ty1P+7QCR771BHV/Khwo3Gj2IxOTMPDZ0VaUZ3M AF8IXSfcI4iV+df8W7KiIIxEguz/ovgSFwsSD1LM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 03/18] libcamera: Unify Doxygen file directive prefix for formats.h Date: Mon, 5 Aug 2024 17:36:39 +0300 Message-ID: <20240805143654.20870-4-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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" libcamera has two formats.h headers, an internal one in include/libcamera/internal/, and a public one generated at build time. The convention is to prefix the internal header name with libcamera/internal/ in the Doxygen file directive, but formats.cpp only uses internal/ as a prefix. Unify it with the rest of the code base. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- src/libcamera/formats.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcamera/formats.cpp b/src/libcamera/formats.cpp index cf41f2c261ed..72fade7cd41c 100644 --- a/src/libcamera/formats.cpp +++ b/src/libcamera/formats.cpp @@ -16,7 +16,7 @@ #include /** - * \file internal/formats.h + * \file libcamera/internal/formats.h * \brief Types and helper functions to handle libcamera image formats */ From patchwork Mon Aug 5 14:36:40 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20790 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 074D0C323E for ; Mon, 5 Aug 2024 14:37:35 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 7351C633B9; Mon, 5 Aug 2024 16:37:34 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="hpO/DXGt"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 1A3D663386 for ; Mon, 5 Aug 2024 16:37:23 +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 8BFD2A06 for ; Mon, 5 Aug 2024 16:36:31 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868591; bh=DSjImp16/qyyNEhA0qPrSOR3ms+J6zDVNNC+1fBP95A=; h=From:To:Subject:Date:In-Reply-To:References:From; b=hpO/DXGtCagZEmWsYxZ+SmXc4hpyemRv63uwi6enJQuJLsfFx9KnBlqEzn36nTMnw PmZf3kxCDKIdosYo9tEf6Qo6RMjtXzFMhbcCVhsuyceYJEN2qA48EyY6Xyj5r0hXct wNRwViUKHb912weNpUZ4qTNkEDg08gh6OiBxHgzU= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 04/18] libcamera: Mark internal parts of public classes with \internal Date: Mon, 5 Aug 2024 17:36:40 +0300 Message-ID: <20240805143654.20870-5-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 libcamera public API exposes classes that have parts considered internal. They inherit the Extensible class, and their internal parts are split into a Private class. Those classes are defined in public API headers, and their Private counterparts are defined in internal headers sharing a common file name (in a different directory). Both headers are documented in the same source file. For instance, include/libcamera/camera.h contains the public API of the Camera class, and include/libcamera/internal/camera.h its internal counterpart. Both are documented in src/libcamera/camera.cpp. As the internal headers are not part of the public API, they need to be hidden from the future public API builds. To prepare for doing so, mark them with the \internal Doxygen directive. Hardcode the Doxygen INTERNAL_DOCS option to YES to include the internal API. This will be changed later for the public API documentation build. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- Documentation/Doxyfile.in | 1 + src/libcamera/camera.cpp | 1 + src/libcamera/camera_manager.cpp | 1 + src/libcamera/framebuffer.cpp | 5 ++++- src/libcamera/request.cpp | 1 + 5 files changed, 8 insertions(+), 1 deletion(-) diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index abafcf6c6c66..62e63968ce62 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -17,6 +17,7 @@ EXTENSION_MAPPING = h=C++ TOC_INCLUDE_HEADINGS = 0 +INTERNAL_DOCS = YES CASE_SENSE_NAMES = YES QUIET = YES diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index f89510ea0472..3c8f30d54401 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -118,6 +118,7 @@ */ /** + * \internal * \file libcamera/internal/camera.h * \brief Internal camera device handling */ diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp index 95a9e3264526..5a21132a08c2 100644 --- a/src/libcamera/camera_manager.cpp +++ b/src/libcamera/camera_manager.cpp @@ -23,6 +23,7 @@ */ /** + * \internal * \file libcamera/internal/camera_manager.h * \brief Internal camera manager support */ diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp index 63d679cb504d..f39db1223432 100644 --- a/src/libcamera/framebuffer.cpp +++ b/src/libcamera/framebuffer.cpp @@ -16,7 +16,10 @@ /** * \file libcamera/framebuffer.h * \brief Frame buffer handling - * + */ + +/** + * \internal * \file libcamera/internal/framebuffer.h * \brief Internal frame buffer handling support */ diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp index fdf12c1e9088..24fa3a57312e 100644 --- a/src/libcamera/request.cpp +++ b/src/libcamera/request.cpp @@ -29,6 +29,7 @@ */ /** + * \internal * \file libcamera/internal/request.h * \brief Internal support for request handling */ From patchwork Mon Aug 5 14:36:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20791 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 0803DC323E for ; Mon, 5 Aug 2024 14:37:38 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 96E68633BD; Mon, 5 Aug 2024 16:37:37 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="ICCxet07"; 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 82F5163387 for ; Mon, 5 Aug 2024 16:37:24 +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 ED46C581 for ; Mon, 5 Aug 2024 16:36:32 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868593; bh=IfyWtTa8yIn6QCZl6VGj/05aOsTlQNTCaR5WUCHzGck=; h=From:To:Subject:Date:In-Reply-To:References:From; b=ICCxet07Stf7icmZ4/snjS8jSHHaEFW5P/F8A0rWtQmLGfgiS8MbcQbiGhtIYA2lN BMjd2n5zloGhQKhaAk1uYN1/tB1AG6dpLzXLVjRtMrdk7IHpEy84ij9OjpEU9AiUFn JwpujR20B95MQlrcoErJhfq+mP2LuLY3KVGrFZDs= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 05/18] libcamera: Hide *::Private classes with __DOXYGEN_PUBLIC__ Date: Mon, 5 Aug 2024 17:36:41 +0300 Message-ID: <20240805143654.20870-6-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 *::Private classes are part of the internal API, as their name implies. They are defined in internal headers, but implemented in the same source file as their public counterparts. This will cause Doxygen to complain about missing class definition when splitting the public and internal API documents, as the internal headers won't be parsed by Doxygen for the public API documentation. Marking the classes with \internal isn't enough. The directive prevents the documentation block from being included in the output, but this occurs at the generation stage, after the documentation blocks are parsed. Fix this by completely hidding the implementation of the *::Private classes from Doxygen using preprocessor conditional compilation. To do so, introduce a new macro, __DOXYGEN_PUBLIC__, that will be defined for the public API documentation only. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Daniel Scally --- src/libcamera/camera.cpp | 2 ++ src/libcamera/camera_manager.cpp | 2 ++ src/libcamera/framebuffer.cpp | 2 ++ src/libcamera/request.cpp | 2 ++ 4 files changed, 8 insertions(+) diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index 3c8f30d54401..aca466c9ba72 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -565,6 +565,7 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF * \brief The vector of stream configurations */ +#ifndef __DOXYGEN_PUBLIC__ /** * \class Camera::Private * \brief Base class for camera private data @@ -725,6 +726,7 @@ void Camera::Private::setState(State state) { state_.store(state, std::memory_order_release); } +#endif /* __DOXYGEN_PUBLIC__ */ /** * \class Camera diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp index 5a21132a08c2..fa44e33a135d 100644 --- a/src/libcamera/camera_manager.cpp +++ b/src/libcamera/camera_manager.cpp @@ -35,6 +35,7 @@ namespace libcamera { LOG_DEFINE_CATEGORY(Camera) +#ifndef __DOXYGEN_PUBLIC__ CameraManager::Private::Private() : initialized_(false) { @@ -249,6 +250,7 @@ void CameraManager::Private::removeCamera(std::shared_ptr camera) CameraManager *const o = LIBCAMERA_O_PTR(); o->cameraRemoved.emit(camera); } +#endif /* __DOXYGEN_PUBLIC__ */ /** * \class CameraManager diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp index f39db1223432..826848f75a56 100644 --- a/src/libcamera/framebuffer.cpp +++ b/src/libcamera/framebuffer.cpp @@ -107,6 +107,7 @@ LOG_DEFINE_CATEGORY(Buffer) * \return The array of per-plane metadata */ +#ifndef __DOXYGEN_PUBLIC__ /** * \class FrameBuffer::Private * \brief Base class for FrameBuffer private data @@ -209,6 +210,7 @@ FrameBuffer::Private::~Private() * \brief Retrieve the dynamic metadata * \return Dynamic metadata for the frame contained in the buffer */ +#endif /* __DOXYGEN_PUBLIC__ */ /** * \class FrameBuffer diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp index 24fa3a57312e..8c56ed30d0c4 100644 --- a/src/libcamera/request.cpp +++ b/src/libcamera/request.cpp @@ -38,6 +38,7 @@ namespace libcamera { LOG_DEFINE_CATEGORY(Request) +#ifndef __DOXYGEN_PUBLIC__ /** * \class Request::Private * \brief Request private data @@ -306,6 +307,7 @@ void Request::Private::timeout() emitPrepareCompleted(); } +#endif /* __DOXYGEN_PUBLIC__ */ /** * \enum Request::Status From patchwork Mon Aug 5 14:36:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20792 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 4DBDDC323E for ; Mon, 5 Aug 2024 14:37:42 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id CF68B633C7; Mon, 5 Aug 2024 16:37:41 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="acfSczXZ"; 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 E07C16338A for ; Mon, 5 Aug 2024 16:37:25 +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 55B74581; Mon, 5 Aug 2024 16:36:34 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868594; bh=kEY9HO99CX38+CHsUx5k+fnQfete750febrmtR1qBfE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=acfSczXZV0aoZhA0f3t/xZeYU6aJj5qeLNLS43cybxZBrd1bim5a46M+2+EdleoFa /hiT6TVLBcMBl5UCDhj72wr+HUJYPZucXgyvDWn2nGBCJMVxL6ETGMVkTSqzywW/3y beKZlat41NNWTojfLGf8z9nsWtDANYbDUCqnd4S8= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v5 06/18] libcamera: Split public and internal source arrays Date: Mon, 5 Aug 2024 17:36:42 +0300 Message-ID: <20240805143654.20870-7-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 Meson array variables hold lists of libcamera's source files. To help facilitate the splitting of Doxygen generated documentation into distinct public and internal versions, split those arrays to separate public and internal variables. Signed-off-by: Daniel Scally Co-developed-by: Laurent Pinchart Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham --- Changes since v4: - Drop the libcamera_base_sources and libcamera_sources variables to avoid incorrect usage in the future - Move the libcamera_internal_headers split to a separate patch to ease review --- Documentation/guides/pipeline-handler.rst | 5 +- Documentation/meson.build | 6 ++- src/libcamera/base/meson.build | 25 +++++---- src/libcamera/converter/meson.build | 2 +- src/libcamera/meson.build | 52 +++++++++++-------- src/libcamera/pipeline/imx8-isi/meson.build | 2 +- src/libcamera/pipeline/ipu3/meson.build | 2 +- src/libcamera/pipeline/mali-c55/meson.build | 2 +- src/libcamera/pipeline/rkisp1/meson.build | 2 +- src/libcamera/pipeline/rpi/common/meson.build | 2 +- src/libcamera/pipeline/rpi/vc4/meson.build | 2 +- src/libcamera/pipeline/simple/meson.build | 2 +- src/libcamera/pipeline/uvcvideo/meson.build | 2 +- src/libcamera/pipeline/vimc/meson.build | 2 +- src/libcamera/proxy/meson.build | 2 +- src/libcamera/sensor/meson.build | 2 +- src/libcamera/software_isp/meson.build | 2 +- 17 files changed, 65 insertions(+), 49 deletions(-) diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst index 7e45cdb84b85..5aa09e90f419 100644 --- a/Documentation/guides/pipeline-handler.rst +++ b/Documentation/guides/pipeline-handler.rst @@ -151,13 +151,14 @@ integrates with the libcamera build system, and a *vivid.cpp* file that matches the name of the pipeline. In the *meson.build* file, add the *vivid.cpp* file as a build source for -libcamera by adding it to the global meson ``libcamera_sources`` variable: +libcamera by adding it to the global meson ``libcamera_internal_sources`` +variable: .. code-block:: none # SPDX-License-Identifier: CC0-1.0 - libcamera_sources += files([ + libcamera_internal_sources += files([ 'vivid.cpp', ]) diff --git a/Documentation/meson.build b/Documentation/meson.build index 30d395234952..070420715bd1 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -31,12 +31,14 @@ if doxygen.found() and dot.found() doxygen_input = [ doxyfile, libcamera_base_headers, - libcamera_base_sources, + libcamera_base_public_sources, + libcamera_base_internal_sources, libcamera_internal_headers, libcamera_ipa_headers, libcamera_ipa_interfaces, libcamera_public_headers, - libcamera_sources, + libcamera_public_sources, + libcamera_internal_sources, libipa_headers, libipa_sources, ] diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build index 4a228d335ba4..a742dfdfeb24 100644 --- a/src/libcamera/base/meson.build +++ b/src/libcamera/base/meson.build @@ -1,25 +1,28 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_base_sources = files([ - 'backtrace.cpp', - 'class.cpp', +libcamera_base_public_sources = files([ 'bound_method.cpp', + 'class.cpp', + 'flags.cpp', + 'object.cpp', + 'shared_fd.cpp', + 'signal.cpp', + 'unique_fd.cpp', +]) + +libcamera_base_internal_sources = files([ + 'backtrace.cpp', 'event_dispatcher.cpp', 'event_dispatcher_poll.cpp', 'event_notifier.cpp', 'file.cpp', - 'flags.cpp', 'log.cpp', 'memfd.cpp', 'message.cpp', 'mutex.cpp', - 'object.cpp', 'semaphore.cpp', - 'shared_fd.cpp', - 'signal.cpp', 'thread.cpp', 'timer.cpp', - 'unique_fd.cpp', 'utils.cpp', ]) @@ -50,7 +53,11 @@ libcamera_base_deps = [ libcamera_base_args = [ '-DLIBCAMERA_BASE_PRIVATE' ] libcamera_base_lib = shared_library('libcamera-base', - [libcamera_base_sources, libcamera_base_headers], + [ + libcamera_base_public_sources, + libcamera_base_internal_sources, + libcamera_base_headers, + ], version : libcamera_version, soversion : libcamera_soversion, name_prefix : '', diff --git a/src/libcamera/converter/meson.build b/src/libcamera/converter/meson.build index 2aa72fe456a4..af1a80fec683 100644 --- a/src/libcamera/converter/meson.build +++ b/src/libcamera/converter/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'converter_v4l2_m2m.cpp' ]) diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 89504cee1146..deffff356091 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -1,14 +1,26 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources = files([ - 'bayer_format.cpp', - 'byte_stream_buffer.cpp', +libcamera_public_sources = files([ 'camera.cpp', - 'camera_controls.cpp', - 'camera_lens.cpp', 'camera_manager.cpp', 'color_space.cpp', 'controls.cpp', + 'fence.cpp', + 'framebuffer.cpp', + 'framebuffer_allocator.cpp', + 'geometry.cpp', + 'orientation.cpp', + 'pixel_format.cpp', + 'request.cpp', + 'stream.cpp', + 'transform.cpp', +]) + +libcamera_internal_sources = files([ + 'bayer_format.cpp', + 'byte_stream_buffer.cpp', + 'camera_controls.cpp', + 'camera_lens.cpp', 'control_serializer.cpp', 'control_validator.cpp', 'converter.cpp', @@ -16,11 +28,7 @@ libcamera_sources = files([ 'device_enumerator.cpp', 'device_enumerator_sysfs.cpp', 'dma_buf_allocator.cpp', - 'fence.cpp', 'formats.cpp', - 'framebuffer.cpp', - 'framebuffer_allocator.cpp', - 'geometry.cpp', 'ipa_controls.cpp', 'ipa_data_serializer.cpp', 'ipa_interface.cpp', @@ -33,17 +41,12 @@ libcamera_sources = files([ 'mapped_framebuffer.cpp', 'media_device.cpp', 'media_object.cpp', - 'orientation.cpp', 'pipeline_handler.cpp', - 'pixel_format.cpp', 'process.cpp', 'pub_key.cpp', - 'request.cpp', 'shared_mem_object.cpp', 'source_paths.cpp', - 'stream.cpp', 'sysfs.cpp', - 'transform.cpp', 'v4l2_device.cpp', 'v4l2_pixelformat.cpp', 'v4l2_subdevice.cpp', @@ -51,9 +54,9 @@ libcamera_sources = files([ 'yaml_parser.cpp', ]) -libcamera_sources += libcamera_public_headers -libcamera_sources += libcamera_generated_ipa_headers -libcamera_sources += libcamera_tracepoint_header +libcamera_public_sources += libcamera_public_headers +libcamera_internal_sources += libcamera_generated_ipa_headers +libcamera_internal_sources += libcamera_tracepoint_header includes = [ libcamera_includes, @@ -104,14 +107,14 @@ endif if liblttng.found() tracing_enabled = true config_h.set('HAVE_TRACING', 1) - libcamera_sources += files(['tracepoints.cpp']) + libcamera_internal_sources += files(['tracepoints.cpp']) else tracing_enabled = false endif if libudev.found() config_h.set('HAVE_LIBUDEV', 1) - libcamera_sources += files([ + libcamera_internal_sources += files([ 'device_enumerator_udev.cpp', ]) endif @@ -152,7 +155,7 @@ foreach mode, input_files : controls_mode_files '-r', ranges_file, '@INPUT@']) endforeach -libcamera_sources += control_sources +libcamera_public_sources += control_sources gen_version = meson.project_source_root() / 'utils' / 'gen-version.sh' @@ -163,7 +166,7 @@ version_cpp = vcs_tag(command : [gen_version, meson.project_build_root(), meson. output : 'version.cpp', fallback : meson.project_version()) -libcamera_sources += version_cpp +libcamera_public_sources += version_cpp if ipa_sign_module ipa_pub_key_cpp = custom_target('ipa_pub_key_cpp', @@ -171,7 +174,7 @@ if ipa_sign_module output : 'ipa_pub_key.cpp', command : [gen_ipa_pub_key, '@INPUT@', '@OUTPUT@']) - libcamera_sources += ipa_pub_key_cpp + libcamera_internal_sources += ipa_pub_key_cpp endif libcamera_deps += [ @@ -191,7 +194,10 @@ libcamera_deps += [ # for the presence or abscence of the dynamic tag. libcamera = shared_library('libcamera', - libcamera_sources, + [ + libcamera_public_sources, + libcamera_internal_sources, + ], version : libcamera_version, soversion : libcamera_soversion, name_prefix : '', diff --git a/src/libcamera/pipeline/imx8-isi/meson.build b/src/libcamera/pipeline/imx8-isi/meson.build index ffd0ce54ce92..b369b03141cb 100644 --- a/src/libcamera/pipeline/imx8-isi/meson.build +++ b/src/libcamera/pipeline/imx8-isi/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'imx8-isi.cpp' ]) diff --git a/src/libcamera/pipeline/ipu3/meson.build b/src/libcamera/pipeline/ipu3/meson.build index a1b0b31ac5bc..f2904b4a8929 100644 --- a/src/libcamera/pipeline/ipu3/meson.build +++ b/src/libcamera/pipeline/ipu3/meson.build @@ -1,6 +1,6 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'cio2.cpp', 'frames.cpp', 'imgu.cpp', diff --git a/src/libcamera/pipeline/mali-c55/meson.build b/src/libcamera/pipeline/mali-c55/meson.build index 30fd29b928d5..eba8e5a39054 100644 --- a/src/libcamera/pipeline/mali-c55/meson.build +++ b/src/libcamera/pipeline/mali-c55/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'mali-c55.cpp' ]) diff --git a/src/libcamera/pipeline/rkisp1/meson.build b/src/libcamera/pipeline/rkisp1/meson.build index cad66535c25f..d21a6ef96bef 100644 --- a/src/libcamera/pipeline/rkisp1/meson.build +++ b/src/libcamera/pipeline/rkisp1/meson.build @@ -1,6 +1,6 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'rkisp1.cpp', 'rkisp1_path.cpp', ]) diff --git a/src/libcamera/pipeline/rpi/common/meson.build b/src/libcamera/pipeline/rpi/common/meson.build index 8fb7e823279d..b2b1a0a61284 100644 --- a/src/libcamera/pipeline/rpi/common/meson.build +++ b/src/libcamera/pipeline/rpi/common/meson.build @@ -1,6 +1,6 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'delayed_controls.cpp', 'pipeline_base.cpp', 'rpi_stream.cpp', diff --git a/src/libcamera/pipeline/rpi/vc4/meson.build b/src/libcamera/pipeline/rpi/vc4/meson.build index 386e2296785a..9b37c2f089f2 100644 --- a/src/libcamera/pipeline/rpi/vc4/meson.build +++ b/src/libcamera/pipeline/rpi/vc4/meson.build @@ -1,6 +1,6 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'vc4.cpp', ]) diff --git a/src/libcamera/pipeline/simple/meson.build b/src/libcamera/pipeline/simple/meson.build index 42b0896dff8b..dda3de9782e4 100644 --- a/src/libcamera/pipeline/simple/meson.build +++ b/src/libcamera/pipeline/simple/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'simple.cpp', ]) diff --git a/src/libcamera/pipeline/uvcvideo/meson.build b/src/libcamera/pipeline/uvcvideo/meson.build index a3c2efd424bf..a3a91074f916 100644 --- a/src/libcamera/pipeline/uvcvideo/meson.build +++ b/src/libcamera/pipeline/uvcvideo/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'uvcvideo.cpp', ]) diff --git a/src/libcamera/pipeline/vimc/meson.build b/src/libcamera/pipeline/vimc/meson.build index 290eefb5d076..868e2546a087 100644 --- a/src/libcamera/pipeline/vimc/meson.build +++ b/src/libcamera/pipeline/vimc/meson.build @@ -1,5 +1,5 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'vimc.cpp', ]) diff --git a/src/libcamera/proxy/meson.build b/src/libcamera/proxy/meson.build index 00ae5a8ffa47..d7de518a0549 100644 --- a/src/libcamera/proxy/meson.build +++ b/src/libcamera/proxy/meson.build @@ -15,5 +15,5 @@ foreach mojom : ipa_mojoms './' + '@INPUT@' ]) - libcamera_sources += proxy + libcamera_internal_sources += proxy endforeach diff --git a/src/libcamera/sensor/meson.build b/src/libcamera/sensor/meson.build index bf4b131a94b1..61234e950d04 100644 --- a/src/libcamera/sensor/meson.build +++ b/src/libcamera/sensor/meson.build @@ -1,6 +1,6 @@ # SPDX-License-Identifier: CC0-1.0 -libcamera_sources += files([ +libcamera_internal_sources += files([ 'camera_sensor.cpp', 'camera_sensor_properties.cpp', ]) diff --git a/src/libcamera/software_isp/meson.build b/src/libcamera/software_isp/meson.build index f7c66e28f9b9..aac7eda7b5b3 100644 --- a/src/libcamera/software_isp/meson.build +++ b/src/libcamera/software_isp/meson.build @@ -7,7 +7,7 @@ if not softisp_enabled subdir_done() endif -libcamera_sources += files([ +libcamera_internal_sources += files([ 'debayer.cpp', 'debayer_cpu.cpp', 'software_isp.cpp', From patchwork Mon Aug 5 14:36:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20793 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 56CA0C323E for ; Mon, 5 Aug 2024 14:37:45 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id D9C79633C1; Mon, 5 Aug 2024 16:37:43 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="CGo+OuaW"; 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 4648A63393 for ; Mon, 5 Aug 2024 16:37:27 +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 C303FA06 for ; Mon, 5 Aug 2024 16:36:35 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868595; bh=SxflEMXIY4kYeY+WB6wEdxStsRYRO/UxYCqJVidxscM=; h=From:To:Subject:Date:In-Reply-To:References:From; b=CGo+OuaWKtjSQKszuKH4S/FAlC723QipkqRJMH5gtaItbx++zLSP3LJjCG210dX4F KKKxe8zhaK8RlAWxVz7c24d2L+RDiX02V9yGLYvtr8n5RkM7HCLKNhybTOoWK49hOd 5xVCyiP9N9lh6gyjgoj4IawxckGCyH7nOSMhHVuk= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 07/18] libcamera: Add version.h to public headers Date: Mon, 5 Aug 2024 17:36:43 +0300 Message-ID: <20240805143654.20870-8-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 generated version.h header is part of the public headers, but is missing from the libcamera_public_headers variable. Add it. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- include/libcamera/meson.build | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/include/libcamera/meson.build b/include/libcamera/meson.build index 84c6c4cb8bf6..c8c900eba66a 100644 --- a/include/libcamera/meson.build +++ b/include/libcamera/meson.build @@ -120,7 +120,8 @@ libcamera_version_config.set('LIBCAMERA_VERSION_MAJOR', version[0]) libcamera_version_config.set('LIBCAMERA_VERSION_MINOR', version[1]) libcamera_version_config.set('LIBCAMERA_VERSION_PATCH', version[2]) -configure_file(input : 'version.h.in', - output : 'version.h', - configuration : libcamera_version_config, - install_dir : libcamera_headers_install_dir) +version_h = configure_file(input : 'version.h.in', + output : 'version.h', + configuration : libcamera_version_config, + install_dir : libcamera_headers_install_dir) +libcamera_public_headers += version_h From patchwork Mon Aug 5 14:36:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20794 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 B072AC323E for ; Mon, 5 Aug 2024 14:37:47 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 4CE3363393; Mon, 5 Aug 2024 16:37:46 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="bEJ0Mkja"; 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 DAC2D63369 for ; Mon, 5 Aug 2024 16:37:28 +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 21276581 for ; Mon, 5 Aug 2024 16:36:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868597; bh=ZxkKQJrNm83Jt5vpY4pVPDXLXAyfTi9eBOoIehRCAdA=; h=From:To:Subject:Date:In-Reply-To:References:From; b=bEJ0MkjaSUVFNLb4rs1O3bR3yLBGL0MPTaJbvpfUhyKQNQyX5KUxd6xXaEIvC0fte fSqT3iYmorEQ5PSPOu2HLcy6rAnLX1yVNfMX2e2uTh1UoZymG1RDkUCyKAHXNUcxKP SH/6LllMOzCK2SgrDHX05QTt08Of3WuzEI3Wv0J4= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 08/18] libcamera: Drop libcamera_generated_ipa_headers from sources Date: Mon, 5 Aug 2024 17:36:44 +0300 Message-ID: <20240805143654.20870-9-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 libcamera_generated_ipa_headers variable, containing the list of generated IPA headers, is listed in the sources of IPA modules, as well as IPA tests. This was done to ensure that the modules and tests get rebuilt when the generate IPA headers change. However, the dependency is already handled through the libcamera_private dependency object, specified for all those modules and tests. There's no need to list the IPA generated headers as sources. Drop them. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- src/ipa/ipu3/meson.build | 3 +-- src/ipa/rkisp1/meson.build | 3 +-- src/ipa/rpi/vc4/meson.build | 3 +-- src/ipa/simple/meson.build | 3 +-- src/ipa/vimc/meson.build | 3 +-- src/libcamera/proxy/worker/meson.build | 3 +-- test/ipa/meson.build | 2 +- test/ipa/rkisp1/meson.build | 2 +- 8 files changed, 8 insertions(+), 14 deletions(-) diff --git a/src/ipa/ipu3/meson.build b/src/ipa/ipu3/meson.build index e76f97c07c87..34de6213aa83 100644 --- a/src/ipa/ipu3/meson.build +++ b/src/ipa/ipu3/meson.build @@ -12,8 +12,7 @@ ipu3_ipa_sources = files([ ipu3_ipa_sources += ipu3_ipa_algorithms -mod = shared_module(ipa_name, - [ipu3_ipa_sources, libcamera_generated_ipa_headers], +mod = shared_module(ipa_name, ipu3_ipa_sources, name_prefix : '', include_directories : [ipa_includes], dependencies : [libcamera_private, libipa_dep], diff --git a/src/ipa/rkisp1/meson.build b/src/ipa/rkisp1/meson.build index e8b266f1ccca..160ef52dd52e 100644 --- a/src/ipa/rkisp1/meson.build +++ b/src/ipa/rkisp1/meson.build @@ -13,8 +13,7 @@ rkisp1_ipa_sources = files([ rkisp1_ipa_sources += rkisp1_ipa_algorithms -mod = shared_module(ipa_name, - [rkisp1_ipa_sources, libcamera_generated_ipa_headers], +mod = shared_module(ipa_name, rkisp1_ipa_sources, name_prefix : '', include_directories : [ipa_includes], dependencies : [libcamera_private, libipa_dep], diff --git a/src/ipa/rpi/vc4/meson.build b/src/ipa/rpi/vc4/meson.build index 63fc5925b06c..c10fa17e1ba4 100644 --- a/src/ipa/rpi/vc4/meson.build +++ b/src/ipa/rpi/vc4/meson.build @@ -23,8 +23,7 @@ vc4_ipa_sources = files([ vc4_ipa_includes += include_directories('..') -mod = shared_module(ipa_name, - [vc4_ipa_sources, libcamera_generated_ipa_headers], +mod = shared_module(ipa_name, vc4_ipa_sources, name_prefix : '', include_directories : vc4_ipa_includes, dependencies : [vc4_ipa_deps, libipa_dep], diff --git a/src/ipa/simple/meson.build b/src/ipa/simple/meson.build index 33d1c96aa4f2..b297e1d2e677 100644 --- a/src/ipa/simple/meson.build +++ b/src/ipa/simple/meson.build @@ -7,8 +7,7 @@ soft_simple_sources = files([ 'black_level.cpp', ]) -mod = shared_module(ipa_name, - [soft_simple_sources, libcamera_generated_ipa_headers], +mod = shared_module(ipa_name, soft_simple_sources, name_prefix : '', include_directories : [ipa_includes], dependencies : [libcamera_private, libipa_dep], diff --git a/src/ipa/vimc/meson.build b/src/ipa/vimc/meson.build index d0b63eddd5f6..2cc5f80b0b69 100644 --- a/src/ipa/vimc/meson.build +++ b/src/ipa/vimc/meson.build @@ -2,8 +2,7 @@ ipa_name = 'ipa_vimc' -mod = shared_module(ipa_name, - ['vimc.cpp', libcamera_generated_ipa_headers], +mod = shared_module(ipa_name, 'vimc.cpp', name_prefix : '', include_directories : [ipa_includes], dependencies : [libcamera_private, libipa_dep], diff --git a/src/libcamera/proxy/worker/meson.build b/src/libcamera/proxy/worker/meson.build index aa4d9cd7b5d8..b5ab9794c622 100644 --- a/src/libcamera/proxy/worker/meson.build +++ b/src/libcamera/proxy/worker/meson.build @@ -17,8 +17,7 @@ foreach mojom : ipa_mojoms './' + '@INPUT@' ]) - proxy = executable(mojom['name'] + '_ipa_proxy', - [worker, libcamera_generated_ipa_headers], + proxy = executable(mojom['name'] + '_ipa_proxy', worker, install : true, install_dir : proxy_install_dir, dependencies : libcamera_private) diff --git a/test/ipa/meson.build b/test/ipa/meson.build index fe21ca58b64f..e9871aba44ee 100644 --- a/test/ipa/meson.build +++ b/test/ipa/meson.build @@ -8,7 +8,7 @@ ipa_test = [ ] foreach test : ipa_test - exe = executable(test['name'], test['sources'], libcamera_generated_ipa_headers, + exe = executable(test['name'], test['sources'], dependencies : [libcamera_private, libipa_dep], link_with : [test_libraries], include_directories : [test_includes_internal]) diff --git a/test/ipa/rkisp1/meson.build b/test/ipa/rkisp1/meson.build index 5b08e2939ce6..894523daf76b 100644 --- a/test/ipa/rkisp1/meson.build +++ b/test/ipa/rkisp1/meson.build @@ -5,7 +5,7 @@ rkisp1_ipa_test = [ ] foreach test : rkisp1_ipa_test - exe = executable(test['name'], test['sources'], libcamera_generated_ipa_headers, + exe = executable(test['name'], test['sources'], dependencies : [libcamera_private, libipa_dep], link_with : [test_libraries], include_directories : [test_includes_internal, From patchwork Mon Aug 5 14:36:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20795 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 D39C8C323E for ; Mon, 5 Aug 2024 14:37:49 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 88CF5633C2; Mon, 5 Aug 2024 16:37:48 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="aThvZ3He"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 2543E63389 for ; Mon, 5 Aug 2024 16:37:30 +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 87113A06 for ; Mon, 5 Aug 2024 16:36:38 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868598; bh=XI6xtJ4lkuXJBtDd7/zvlACatUPJ0QsoCk9TZ5fPSEM=; h=From:To:Subject:Date:In-Reply-To:References:From; b=aThvZ3HeeN6hYaGaE71fMqu2B03vJly0usABVJtJbIOBfYojWO5lN6+fusFBToMJ3 uIzcuuiNn7bbakyL6wDHn4itZWwWKDWKgKgkL7F/YgoRv2/RfS13IMocpm0GMmd4gr u8+1L/PmptXJYQIsLTAJ56Urx0H8hndpFr44N3B4= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 09/18] libcamera: Move IPA headers to the libcamera_private dependency Date: Mon, 5 Aug 2024 17:36:45 +0300 Message-ID: <20240805143654.20870-10-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 IPA headers are listed in the libcamera_public and libcamera_private dependency objects, with the generated headers part of the private dependency object and the non-generated headers part of the public dependency object. As neither set of IPA headers are part of the public API, list them both in the libcamera_private dependency object. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- src/libcamera/meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index deffff356091..61a97c738ae8 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -207,7 +207,6 @@ libcamera = shared_library('libcamera', dependencies : libcamera_deps) libcamera_public = declare_dependency(sources : [ - libcamera_ipa_headers, libcamera_public_headers, ], include_directories : libcamera_includes, @@ -216,6 +215,7 @@ libcamera_public = declare_dependency(sources : [ # Internal dependency for components and plugins which can use private APIs libcamera_private = declare_dependency(sources : [ + libcamera_ipa_headers, libcamera_generated_ipa_headers, ], dependencies : [ From patchwork Mon Aug 5 14:36:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20796 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 72E1EC323E for ; Mon, 5 Aug 2024 14:37:52 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 39491633C8; Mon, 5 Aug 2024 16:37:51 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="VtMqXAgR"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 84C1963398 for ; Mon, 5 Aug 2024 16:37:31 +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 0095E581 for ; Mon, 5 Aug 2024 16:36:39 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868600; bh=KBwFDhHay3XV7bBWXBYUAofmofOWYOxmP+CKgFMsMVU=; h=From:To:Subject:Date:In-Reply-To:References:From; b=VtMqXAgRInbP1zZBPJKhntYIMs5ouR2hPBO0DYaC8Zai9wQFHTmsMI5av5UCNrj7n KJeNJK35DH4ZATA2YwjavzAIfR/t5Yo78/XMsh/s9zncrjn4kyUc1HjiYF6h3HpIos LoKxheEostUaBEaVD9yNy5cFNMi+j8oJJAkw99yM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 10/18] libcamera: Consolidate all IPA headers in libcamera_ipa_headers Date: Mon, 5 Aug 2024 17:36:46 +0300 Message-ID: <20240805143654.20870-11-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 IPA headers are listed in two different meson variables, one for generated headers, and one for the other headers. There's no real reason for this split, consolidate all of them in the libcamera_ipa_headers variable. While at it, don't add the IPA headers to the libcamera_internal_sources variable, but list libcamera_ipa_headers in the sources for the shared library. This moves the libcamera_internal_sources variable towards holding source files, not header files, to improve clarity of the build system. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- include/libcamera/ipa/meson.build | 8 +++----- src/libcamera/meson.build | 3 +-- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/include/libcamera/ipa/meson.build b/include/libcamera/ipa/meson.build index 3352d08fbd98..96fca42cc0b8 100644 --- a/include/libcamera/ipa/meson.build +++ b/include/libcamera/ipa/meson.build @@ -11,8 +11,6 @@ libcamera_ipa_headers = files([ install_headers(libcamera_ipa_headers, subdir : libcamera_ipa_include_dir) -libcamera_generated_ipa_headers = [] - ipa_headers_install_dir = get_option('includedir') / libcamera_ipa_include_dir # @@ -31,7 +29,7 @@ ipa_mojom_core = custom_target(core_mojom_file.split('.')[0] + '_mojom_module', ]) # core_ipa_interface.h -libcamera_generated_ipa_headers += custom_target('core_ipa_interface_h', +libcamera_ipa_headers += custom_target('core_ipa_interface_h', input : ipa_mojom_core, output : 'core_ipa_interface.h', depends : mojom_templates, @@ -47,7 +45,7 @@ libcamera_generated_ipa_headers += custom_target('core_ipa_interface_h', ]) # core_ipa_serializer.h -libcamera_generated_ipa_headers += custom_target('core_ipa_serializer_h', +libcamera_ipa_headers += custom_target('core_ipa_serializer_h', input : ipa_mojom_core, output : 'core_ipa_serializer.h', depends : mojom_templates, @@ -152,7 +150,7 @@ foreach pipeline, file : pipeline_ipa_mojom_mapping 'mojom': mojom, } - libcamera_generated_ipa_headers += [header, serializer, proxy_header] + libcamera_ipa_headers += [header, serializer, proxy_header] endforeach ipa_mojom_files = [] diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 61a97c738ae8..86e8b88cc1b2 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -55,7 +55,6 @@ libcamera_internal_sources = files([ ]) libcamera_public_sources += libcamera_public_headers -libcamera_internal_sources += libcamera_generated_ipa_headers libcamera_internal_sources += libcamera_tracepoint_header includes = [ @@ -196,6 +195,7 @@ libcamera_deps += [ libcamera = shared_library('libcamera', [ libcamera_public_sources, + libcamera_ipa_headers, libcamera_internal_sources, ], version : libcamera_version, @@ -216,7 +216,6 @@ libcamera_public = declare_dependency(sources : [ # Internal dependency for components and plugins which can use private APIs libcamera_private = declare_dependency(sources : [ libcamera_ipa_headers, - libcamera_generated_ipa_headers, ], dependencies : [ libcamera_public, From patchwork Mon Aug 5 14:36:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20797 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 4286CC323E for ; Mon, 5 Aug 2024 14:37:55 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 962A163389; Mon, 5 Aug 2024 16:37:53 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="Q8EBvjEb"; 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 0EDDA633AC for ; Mon, 5 Aug 2024 16:37:33 +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 7763FA06 for ; Mon, 5 Aug 2024 16:36:41 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868601; bh=hPdSNg5s2lT3COaYZqPB0WsD8LQskuALQ8Axm6siAmc=; h=From:To:Subject:Date:In-Reply-To:References:From; b=Q8EBvjEbzSeL0Gdw7k3SEVCCKbSvFemlKC8ZjQynQOAq3YpvbuoXU5Z41lvTvAQMI zc0gF8Ez5LRVyaPd/USQtsoiE2Nx5AXAXu2vb2c02wFcC4uC//wfKPAgnKw+IvgePY 5N0539rKnA17Xd1RQ8M/fCzvNThjgqy24VVyQwrw= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 11/18] libcamera: Add missing headers to libcamera_internal_headers Date: Mon, 5 Aug 2024 17:36:47 +0300 Message-ID: <20240805143654.20870-12-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 ipa_data_serializer.h and ipc_pipe.h headers are missing from libcamera_internal_headers. Add them. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- include/libcamera/internal/meson.build | 2 ++ 1 file changed, 2 insertions(+) diff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build index 9713ea1cc27e..f96cc5e37c23 100644 --- a/include/libcamera/internal/meson.build +++ b/include/libcamera/internal/meson.build @@ -28,9 +28,11 @@ libcamera_internal_headers = files([ 'dma_buf_allocator.h', 'formats.h', 'framebuffer.h', + 'ipa_data_serializer.h', 'ipa_manager.h', 'ipa_module.h', 'ipa_proxy.h', + 'ipc_pipe.h', 'ipc_unixsocket.h', 'mapped_framebuffer.h', 'media_device.h', From patchwork Mon Aug 5 14:36:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20798 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 32336C323E for ; Mon, 5 Aug 2024 14:37:57 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 12998633C8; Mon, 5 Aug 2024 16:37:56 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="uhk5lBdx"; 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 6E917633B5 for ; Mon, 5 Aug 2024 16:37: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 D84B0581 for ; Mon, 5 Aug 2024 16:36:42 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868603; bh=NC4ukbdD482fvuYs9QTMC0cCYWETUgJ3CaseMtMUgnE=; h=From:To:Subject:Date:In-Reply-To:References:From; b=uhk5lBdxoyB7Zvy3WYsygfvph62vuQqafxNDDHvgezz9afUNMND5nwaf2xfncP8EW VKJwqpVS5ouvZcbwt9YrbYal5EiZmxhBEMIFeYM1jwJR462MGeeaJuML2fcgqnEHcN 7VQ/MKsDyH9s1Xn/OKO/ERJ/PeLVJJU9JMAdvcgM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 12/18] libcamera: Consolidate tracepoint header in libcamera_internal_headers Date: Mon, 5 Aug 2024 17:36:48 +0300 Message-ID: <20240805143654.20870-13-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 libcamera_tracepoint_header variable stores the tracepoints.h header custom target, for the sole purpose of being listed as a source of the libcamera shared library, through the libcamera_internal_sources variable. Add the tracepoints.h header to libcamera_internal_headers instead of libcamera_internal_sources, and list libcamera_internal_headers as a source of the shared library, alongside libcamera_internal_sources. This makes libcamera_internal_sources contain sources only, improving clarity of the build system variables. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham --- include/libcamera/internal/meson.build | 16 +++++++++------- src/libcamera/meson.build | 2 +- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build index f96cc5e37c23..39230facc8a4 100644 --- a/include/libcamera/internal/meson.build +++ b/include/libcamera/internal/meson.build @@ -2,13 +2,6 @@ subdir('tracepoints') -libcamera_tracepoint_header = custom_target( - 'tp_header', - input : ['tracepoints.h.in', tracepoint_files], - output : 'tracepoints.h', - command : [gen_tracepoints_header, include_build_dir, '@OUTPUT@', '@INPUT@'], -) - libcamera_internal_headers = files([ 'bayer_format.h', 'byte_stream_buffer.h', @@ -51,5 +44,14 @@ libcamera_internal_headers = files([ 'yaml_parser.h', ]) +tracepoints_h = custom_target( + 'tp_header', + input : ['tracepoints.h.in', tracepoint_files], + output : 'tracepoints.h', + command : [gen_tracepoints_header, include_build_dir, '@OUTPUT@', '@INPUT@'], +) + +libcamera_internal_headers += tracepoints_h + subdir('converter') subdir('software_isp') diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 86e8b88cc1b2..6a7c9d77dfd8 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -55,7 +55,6 @@ libcamera_internal_sources = files([ ]) libcamera_public_sources += libcamera_public_headers -libcamera_internal_sources += libcamera_tracepoint_header includes = [ libcamera_includes, @@ -196,6 +195,7 @@ libcamera = shared_library('libcamera', [ libcamera_public_sources, libcamera_ipa_headers, + libcamera_internal_headers, libcamera_internal_sources, ], version : libcamera_version, From patchwork Mon Aug 5 14:36:49 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20799 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 CF31AC323E for ; Mon, 5 Aug 2024 14:38:00 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 436B4633CE; Mon, 5 Aug 2024 16:38:00 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="iJGp4AfW"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id BFD08633B1 for ; Mon, 5 Aug 2024 16:37:35 +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 42B74581 for ; Mon, 5 Aug 2024 16:36:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868604; bh=mZwE4sCtry+LedLLMW1vya+wEL4sqITu/xo/xumq664=; h=From:To:Subject:Date:In-Reply-To:References:From; b=iJGp4AfWyfkovf+xzbKQGdi36xRmASKfFi2Bb1kq7TeEXEtfaO36eQoX9NMbTo36e 8EtzLcntJAud+alL2a9BdD1PkXgKkevYJ/q+Xsuzk5NqBYWrwFkn9w8Xh2brEHaimP 8uJGcK1IVhA/zKIcxenzsxnKEyUhP2lqp+mRULbA= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 13/18] libcamera: Don't add libcamera_public_headers to libcamera_public_sources Date: Mon, 5 Aug 2024 17:36:49 +0300 Message-ID: <20240805143654.20870-14-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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" Now that libcamera_internal_sources is separate from libcamera_internal_headers, perform the same split for libcamera_public_sources and libcamera_public_headers to ensure consistency of the build system variables. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham --- src/libcamera/meson.build | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index 6a7c9d77dfd8..c3efc5278ec8 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -54,8 +54,6 @@ libcamera_internal_sources = files([ 'yaml_parser.cpp', ]) -libcamera_public_sources += libcamera_public_headers - includes = [ libcamera_includes, ] @@ -193,6 +191,7 @@ libcamera_deps += [ libcamera = shared_library('libcamera', [ + libcamera_public_headers, libcamera_public_sources, libcamera_ipa_headers, libcamera_internal_headers, From patchwork Mon Aug 5 14:36:50 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20800 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 41623C323E for ; Mon, 5 Aug 2024 14:38:03 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id CBE01633CB; Mon, 5 Aug 2024 16:38:02 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="qr954QoL"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 3C26D63387 for ; Mon, 5 Aug 2024 16:37: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 A9906581; Mon, 5 Aug 2024 16:36:45 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868605; bh=LvAu4hGvEP8ZD/cqX5EvLhlb4PGOskR21ySZOIdeq3Q=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qr954QoLvyr+PrCOng/WhJlik3bEg545mriWOOdJiZbys+1PrUX4zbIiB4+jr136t XtfsBQWOszUjucJ8eD5OiLerMmsKFUzc0FmSij/yG+U3ikfvupqIbn7aAh+SHhmp/J D/pVH/yKxLPZoZ8H4Twx7vn9OQAYQqdRXUoKsPPM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v5 14/18] Documentation: Add Thread support page Date: Mon, 5 Aug 2024 17:36:50 +0300 Message-ID: <20240805143654.20870-15-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 Thread Support page and the section of the Thread class' documentation dealing with stopping threads from src/libcamera/base/thread.cpp 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. Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham Signed-off-by: Daniel Scally --- Documentation/Doxyfile.in | 4 +- Documentation/thread.dox | 122 +++++++++++++++++++++++++++++++++ src/libcamera/base/thread.cpp | 123 ---------------------------------- 3 files changed, 125 insertions(+), 124 deletions(-) create mode 100644 Documentation/thread.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.dox b/Documentation/thread.dox new file mode 100644 index 000000000000..805a864eef12 --- /dev/null +++ b/Documentation/thread.dox @@ -0,0 +1,122 @@ +/** + * \page thread Thread Support + * + * libcamera supports multi-threaded applications through a threading model that + * sets precise rules to guarantee thread-safe usage of the API. Additionally, + * libcamera makes internal use of threads, and offers APIs that simplify + * interactions with application threads. Careful compliance with the threading + * model will ensure avoidance of race conditions. + * + * Every thread created by libcamera is associated with an instance of the + * Thread class. Those threads run an internal event loop by default to + * dispatch events to objects. Additionally, the main thread of the application + * (defined as the thread that calls CameraManager::start()) is also associated + * with a Thread instance, but has no event loop accessible to libcamera. Other + * application threads are not visible to libcamera. + * + * \section thread-objects Threads and Objects + * + * Instances of the Object class and all its derived classes are thread-aware + * and are bound to the thread they are created in. They are said to *live* in + * a thread, and they interact with the event loop of their thread for the + * purpose of message passing and signal delivery. Messages posted to the + * object with Object::postMessage() will be delivered from the event loop of + * the thread that the object lives in. Signals delivered to the object, unless + * explicitly connected with ConnectionTypeDirect, will also be delivered from + * the object thread's event loop. + * + * All Object instances created internally by libcamera are bound to internal + * threads. As objects interact with thread event loops for proper operation, + * creating an Object instance in a thread that has no internal event loop (such + * as the main application thread, or libcamera threads that have a custom main + * loop), prevents some features of the Object class from being used. See + * Thread::exec() for more details. + * + * \section thread-signals Threads and Signals + * + * When sent to a receiver that does not inherit from the Object class, signals + * are delivered synchronously in the thread of the sender. When the receiver + * inherits from the Object class, delivery is by default asynchronous if the + * sender and receiver live in different threads. In that case, the signal is + * posted to the receiver's message queue and will be delivered from the + * 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. + * + * \section thread-stop Stopping Threads + * + * Threads can't be forcibly stopped. Instead, a thread user first requests the + * thread to exit and then waits for the thread's main function to react to the + * request and return, at which points the thread will stop. + * + * For threads running exec(), the exit() function is used to request the thread + * to exit. For threads subclassing the Thread class and implementing a custom + * run() function, a subclass-specific mechanism shall be provided. In either + * case, the wait() function shall be called to wait for the thread to stop. + * + * Due to their asynchronous nature, threads are subject to race conditions when + * they stop. This is of particular importance for messages posted to the thread + * with postMessage() (and the other mechanisms that rely on it, such as + * Object::invokeMethod() or asynchronous signal delivery). To understand the + * issues, three contexts need to be considered: + * + * - The worker is the Thread performing work and being instructed to stop. + * - The controller is the context which instructs the worker thread to stop. + * - The other contexts are any threads other than the worker and controller + * that interact with the worker thread. + * + * Messages posted to the worker thread from the controller context before + * calling exit() are queued to the thread's message queue, and the Thread class + * offers no guarantee that those messages will be processed before the thread + * stops. This allows threads to stop fast. + * + * A thread that requires delivery of messages posted from the controller + * context before exit() should reimplement the run() function and call + * dispatchMessages() after exec(). + * + * Messages posted to the worker thread from the other contexts are asynchronous + * with respect to the exit() call from the controller context. There is no + * guarantee as to whether those messages will be processed or not before the + * thread stops. + * + * Messages that are not processed will stay in the queue, in the exact same way + * as messages posted after the thread has stopped. They will be processed when + * the thread is restarted. If the thread is never restarted, they will be + * deleted without being processed when the Thread instance is destroyed. + */ diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp index 72733431a22e..1962dd32787c 100644 --- a/src/libcamera/base/thread.cpp +++ b/src/libcamera/base/thread.cpp @@ -20,88 +20,6 @@ #include #include -/** - * \page thread Thread Support - * - * libcamera supports multi-threaded applications through a threading model that - * sets precise rules to guarantee thread-safe usage of the API. Additionally, - * libcamera makes internal use of threads, and offers APIs that simplify - * interactions with application threads. Careful compliance with the threading - * model will ensure avoidance of race conditions. - * - * Every thread created by libcamera is associated with an instance of the - * Thread class. Those threads run an internal event loop by default to - * dispatch events to objects. Additionally, the main thread of the application - * (defined as the thread that calls CameraManager::start()) is also associated - * with a Thread instance, but has no event loop accessible to libcamera. Other - * application threads are not visible to libcamera. - * - * \section thread-objects Threads and Objects - * - * Instances of the Object class and all its derived classes are thread-aware - * and are bound to the thread they are created in. They are said to *live* in - * a thread, and they interact with the event loop of their thread for the - * purpose of message passing and signal delivery. Messages posted to the - * object with Object::postMessage() will be delivered from the event loop of - * the thread that the object lives in. Signals delivered to the object, unless - * explicitly connected with ConnectionTypeDirect, will also be delivered from - * the object thread's event loop. - * - * All Object instances created internally by libcamera are bound to internal - * threads. As objects interact with thread event loops for proper operation, - * creating an Object instance in a thread that has no internal event loop (such - * as the main application thread, or libcamera threads that have a custom main - * loop), prevents some features of the Object class from being used. See - * Thread::exec() for more details. - * - * \section thread-signals Threads and Signals - * - * When sent to a receiver that does not inherit from the Object class, signals - * are delivered synchronously in the thread of the sender. When the receiver - * inherits from the Object class, delivery is by default asynchronous if the - * sender and receiver live in different threads. In that case, the signal is - * posted to the receiver's message queue and will be delivered from the - * 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. - */ - /** * \file base/thread.h * \brief Thread support @@ -217,47 +135,6 @@ ThreadData *ThreadData::current() * called. The event loop dispatches events (messages, notifiers and timers) * sent to the objects living in the thread. This behaviour can be modified by * overriding the run() function. - * - * \section thread-stop Stopping Threads - * - * Threads can't be forcibly stopped. Instead, a thread user first requests the - * thread to exit and then waits for the thread's main function to react to the - * request and return, at which points the thread will stop. - * - * For threads running exec(), the exit() function is used to request the thread - * to exit. For threads subclassing the Thread class and implementing a custom - * run() function, a subclass-specific mechanism shall be provided. In either - * case, the wait() function shall be called to wait for the thread to stop. - * - * Due to their asynchronous nature, threads are subject to race conditions when - * they stop. This is of particular importance for messages posted to the thread - * with postMessage() (and the other mechanisms that rely on it, such as - * Object::invokeMethod() or asynchronous signal delivery). To understand the - * issues, three contexts need to be considered: - * - * - The worker is the Thread performing work and being instructed to stop. - * - The controller is the context which instructs the worker thread to stop. - * - The other contexts are any threads other than the worker and controller - * that interact with the worker thread. - * - * Messages posted to the worker thread from the controller context before - * calling exit() are queued to the thread's message queue, and the Thread class - * offers no guarantee that those messages will be processed before the thread - * stops. This allows threads to stop fast. - * - * A thread that requires delivery of messages posted from the controller - * context before exit() should reimplement the run() function and call - * dispatchMessages() after exec(). - * - * Messages posted to the worker thread from the other contexts are asynchronous - * with respect to the exit() call from the controller context. There is no - * guarantee as to whether those messages will be processed or not before the - * thread stops. - * - * Messages that are not processed will stay in the queue, in the exact same way - * as messages posted after the thread has stopped. They will be processed when - * the thread is restarted. If the thread is never restarted, they will be - * deleted without being processed when the Thread instance is destroyed. */ /** From patchwork Mon Aug 5 14:36:51 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20801 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 D472CC323E for ; Mon, 5 Aug 2024 14:38:05 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5A839633CB; Mon, 5 Aug 2024 16:38:05 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="unjAAZR3"; 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 A0628633BA for ; Mon, 5 Aug 2024 16:37:38 +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 1A664581 for ; Mon, 5 Aug 2024 16:36:47 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868607; bh=e3lHYmv0D/SfbZHbgIE9a1/bKT7GpUx1wM6BVpMgfcE=; h=From:To:Subject:Date:In-Reply-To:References:From; b=unjAAZR37NsgjyCH6npIQ484F06/rIq9VTjbtm78RC0k9VqjClpsUPVdO35cAwP6u DrHFsxJcvUtXp7nkfEFXqukDCJT5y/84dhSe91io9+8sQnBJ2oQ/6XL1tcLC5DwoxG dKDvWilOCoYmWBpzWagVcN0fd0nsgPntMKNofxIo= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 15/18] Documentation: Split doxygen_input in public and internal inputs Date: Mon, 5 Aug 2024 17:36:51 +0300 Message-ID: <20240805143654.20870-16-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 Mon Aug 5 14:36:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20802 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 4A2B0C324E for ; Mon, 5 Aug 2024 14:38:07 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id AFCB1633D4; Mon, 5 Aug 2024 16:38:06 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="c2/41Ch0"; 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 18227633C0 for ; Mon, 5 Aug 2024 16:37: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 83AA1581; Mon, 5 Aug 2024 16:36:48 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868608; bh=ispsSPYU/3d0NK6P5VOqEb5IFL6Rj+LwGobiGeaLKhA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=c2/41Ch02kbWbrC7tLBqzEbiWtF8LsHXMJEDl1ZfOgj8NRsByEOGZTYb18aDRlbEE nyJVvYI6emILYXJXxzIL8Olu9xLNB1VenjST/DbgS3zbfkQ0irojsKXJloLKatGRm2 8O3ObI4Q99ovK5lQk0ZMxPWg6oAl2tu+anjoa87A= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v5 16/18] Documentation: Split public/private documentation Date: Mon, 5 Aug 2024 17:36:52 +0300 Message-ID: <20240805143654.20870-17-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 --- .../{Doxyfile.in => Doxyfile-common.in} | 24 ------- Documentation/Doxyfile-internal.in | 30 ++++++++ Documentation/Doxyfile-public.in | 20 ++++++ Documentation/gen-doxyfile.py | 46 ++++++++++++ Documentation/meson.build | 70 +++++++++++++++++-- 5 files changed, 160 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..c2a4184dd195 --- /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): + + # Parse command line arguments + 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..bf28233a2ce8 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,75 @@ 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. We collected a list of the public sources in + # doxygen_public_sources to pass to the public run and include it in cdata + # here - although both Doxyfile and Doxyfile-internal will also receive + # the same parameter they simply ignore it. + + # 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) + + 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_tmpl = configure_file(input : 'Doxyfile-internal.in', + output : 'Doxyfile-internal.tmpl', + configuration : cdata) + + doxyfile = custom_target('doxyfile-internal', + input : [ + doxygen_public_input, + doxygen_internal_input, + ], + output : 'Doxyfile-internal', + command : [ + 'gen-doxyfile.py', + '-o', '@OUTPUT@', + doxyfile_tmpl, + '@INPUT@', + ]) + + custom_target('doxygen-internal', + input : [ + doxyfile, + doxyfile_common, + ], + output : 'internal-api-html', + command : [doxygen, doxyfile], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc-internal') endif # From patchwork Mon Aug 5 14:36:53 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20803 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 9746BC323E for ; Mon, 5 Aug 2024 14:38:09 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 1D980633BF; Mon, 5 Aug 2024 16:38:09 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="fm5SFHSa"; 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 78154633C3 for ; Mon, 5 Aug 2024 16:37:41 +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 EA326581; Mon, 5 Aug 2024 16:36:49 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868610; bh=JdX1wf465nKXe4Y64c6ARzhJaj1/TZdocqXuGhVqcEY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=fm5SFHSaIZLrbiMkkOwlfyL2OWk6qZ1uFqU3FUZhxdqguAVTxaC09fCNZAYay2ThG Hc5u9jeO7vuyKPXhksUqEy09XjAR+3Giyd4GHW+71Cd18I9WUCWGZ7TbXk/OKV8YO5 qkqZJjk/exRdLLwDxzu32cOBxxzKoOvLsDgEFlOc= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v5 17/18] Documentation: Improve doxygen main page Date: Mon, 5 Aug 2024 17:36:53 +0300 Message-ID: <20240805143654.20870-18-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 Mon Aug 5 14:36:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 20804 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 37BC0C324E for ; Mon, 5 Aug 2024 14:38:11 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 5DA8A633C1; Mon, 5 Aug 2024 16:38:10 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="ZngOiEXn"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id DCC05633C4 for ; Mon, 5 Aug 2024 16:37:42 +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 54113581 for ; Mon, 5 Aug 2024 16:36:51 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1722868611; bh=juZx5tsGK538pLrfMlpqKJvIwySopRRWmT1s1bkqcFc=; h=From:To:Subject:Date:In-Reply-To:References:From; b=ZngOiEXnpxbEuJlWTlnqbvSlbI+DVC9AVgOo5PrJEpDWKPxA+HbduIkxny6kKx2s/ iKX8eYNtGIw7bKkYFOfkNjAk8xfqmHtW0VtN7dptV5VjFQahw0hMwqP/G7XPJsY2Er YCMGsZtkNo01CZCrqYAQYIi/q8dbTR4jyGYzaMZA= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v5 18/18] libcamera: camera: Hide Camera::create() from the public API Date: Mon, 5 Aug 2024 17:36:54 +0300 Message-ID: <20240805143654.20870-19-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.44.2 In-Reply-To: <20240805143654.20870-1-laurent.pinchart@ideasonboard.com> References: <20240805143654.20870-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 --- 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