From patchwork Thu May 27 07:28:01 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 12438 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 20BD7C3203 for ; Thu, 27 May 2021 07:28:22 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id D41C668926; Thu, 27 May 2021 09:28:21 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="ugexjRnM"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 05B8D68922 for ; Thu, 27 May 2021 09:28:20 +0200 (CEST) Received: from pyrite.rasen.tech (unknown [IPv6:2400:4051:61:600:2c71:1b79:d06d:5032]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id A17AF8DE; Thu, 27 May 2021 09:28:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1622100499; bh=tMfrxX9B2T9sVXPgvMxRyLpEATqYD49uGqyijlbGOjo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ugexjRnMgrCkWhk2FneESFv9a/YHCoVzLgBTOQXjOfiJOC6nn/Ewdhje6aQUjUOAD N0tWhuXT57qpjvjlWss0E0a8GHZp/pkHZ1OJYLJ80evvAeVkB3pqLrEtGsj0FR1j0E 2/xDXzOVxM5vTX9R+01O5LXBBhhrV+joBWa1k5lk= From: Paul Elder To: libcamera-devel@lists.libcamera.org Date: Thu, 27 May 2021 16:28:01 +0900 Message-Id: <20210527072805.1333870-2-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210527072805.1333870-1-paul.elder@ideasonboard.com> References: <20210527072805.1333870-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 1/5] utils: ipc: Add script to extract doxygen docs from mojom files X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Add a script to extract doxygen documentation comments from mojom files. It matches based on ^\/\*\*$ for start of block and ^ \*\/$ for end of block, and simply copies the comments to the output file along with a header and the libcamera namespace. Also add it to the meson file so it is usable by other meson files. Signed-off-by: Paul Elder Acked-by: Umang Jain Reviewed-by: Laurent Pinchart --- utils/ipc/extract-docs.py | 74 +++++++++++++++++++++++++++++++++++++++ utils/ipc/meson.build | 2 ++ 2 files changed, 76 insertions(+) create mode 100755 utils/ipc/extract-docs.py diff --git a/utils/ipc/extract-docs.py b/utils/ipc/extract-docs.py new file mode 100755 index 00000000..56566ce0 --- /dev/null +++ b/utils/ipc/extract-docs.py @@ -0,0 +1,74 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (C) 2021, Google Inc. +# +# Author: Paul Elder +# +# extract-docs.py - Extract doxygen documentation from mojom files + +import argparse +import re +import sys + +regex_block_start = re.compile('^\/\*\*$') +regex_block_end = re.compile('^ \*\/$') + + +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('input', type=str, + help='Input file name.') + args = parser.parse_args(argv[1:]) + + lines = open(args.input, 'r').readlines() + pipeline = args.input.split('/')[-1].replace('.mojom', '') + data = f'''\ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2021, Google Inc. + * + * {pipeline}_ipa_interface.cpp - Docs file for generated {pipeline}.mojom + * + * This file is auto-generated. Do not edit. + */ + +namespace libcamera {{ + +''' + + in_block = False + comment = '' + for lineno, line in enumerate(lines, start=1): + if regex_block_start.match(line): + if in_block: + raise SyntaxError('Expected end of comment', + (args.input, lineno, 1, line)) + in_block = True + comment = line + continue + + if regex_block_end.match(line): + if in_block: + comment += line + data += comment + '\n' + in_block = False + continue + + if in_block: + comment += line + + data += '} /* namespace libcamera */\n' + + args.output.write(data) + + return 0 + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/utils/ipc/meson.build b/utils/ipc/meson.build index 4a41b9c1..973a5417 100644 --- a/utils/ipc/meson.build +++ b/utils/ipc/meson.build @@ -8,6 +8,8 @@ mojom_parser = find_program('./parser.py') mojom_generator = find_program('./generate.py') +mojom_docs_extractor = find_program('./extract-docs.py') + mojom_templates = custom_target('mojom_templates', input : mojom_template_files, output : 'libcamera_templates.zip', From patchwork Thu May 27 07:28:03 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Elder X-Patchwork-Id: 12439 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 0FE19C3203 for ; Thu, 27 May 2021 07:28:26 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id C406768925; Thu, 27 May 2021 09:28:25 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="XKkF/WHq"; 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 6A27F68925 for ; Thu, 27 May 2021 09:28:24 +0200 (CEST) Received: from pyrite.rasen.tech (unknown [IPv6:2400:4051:61:600:2c71:1b79:d06d:5032]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 9B06B8DE; Thu, 27 May 2021 09:28:22 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1622100504; bh=wnoIsIKL/jGDHLNA4uP8tFMfS1nJk5ncjzDQT9cZKhA=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=XKkF/WHqYUpp1zJvHGIysvhaONTu8KyJbmlvxqsXn1MAI9HwvQQKVhXPr77GluIym jyUnalzjrr8F/t5hJ6V/b1I+7tnaQcAcSQeRa5xdHPBPp0U9/pEKqc5VVUUAIj/G7k mQd6DyeCTtyb5ddBZb4lPAP+URnoq/l/IwNubDPY= From: Paul Elder To: libcamera-devel@lists.libcamera.org Date: Thu, 27 May 2021 16:28:03 +0900 Message-Id: <20210527072805.1333870-4-paul.elder@ideasonboard.com> X-Mailer: git-send-email 2.27.0 In-Reply-To: <20210527072805.1333870-1-paul.elder@ideasonboard.com> References: <20210527072805.1333870-1-paul.elder@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v3 3/5] ipa: core: Move documentation from cpp file back into the mojom file 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" Move the documentation back to the mojom file from the cpp file. While at it, move the documentation for IPAInterface::init() and IPAInterface::stop() to the IPA guide. Signed-off-by: Paul Elder Reviewed-by: Laurent Pinchart Reviewed-by: Umang Jain --- Changes in v3: - remove core_ipa_interface.cpp --- Documentation/guides/ipa.rst | 6 + include/libcamera/ipa/core.mojom | 200 +++++++++++++++++++++-- src/libcamera/ipa/core_ipa_interface.cpp | 199 ---------------------- 3 files changed, 190 insertions(+), 215 deletions(-) delete mode 100644 src/libcamera/ipa/core_ipa_interface.cpp diff --git a/Documentation/guides/ipa.rst b/Documentation/guides/ipa.rst index 6195b2b7..c612470f 100644 --- a/Documentation/guides/ipa.rst +++ b/Documentation/guides/ipa.rst @@ -166,6 +166,12 @@ At a minimum, the following three functions must be present (and implemented): All three of these functions are synchronous. The parameters for start() and init() may be customized. +init() initializes the IPA interface. It shall be called before any other +function of the IPAInterface. + +stop() informs the IPA module that the camera is stopped. The IPA module shall +release resources prepared in start(). + A configure() method is recommended. Any ControlInfoMap instances that will be used by the IPA must be sent to the IPA from the pipeline handler, at configure time, for example. diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom index 34a799c2..b32f3093 100644 --- a/include/libcamera/ipa/core.mojom +++ b/include/libcamera/ipa/core.mojom @@ -2,6 +2,11 @@ module libcamera; +/** + * \file core_ipa_interface.h + * \brief libcamera structs for IPAs + */ + /* * Things that can be defined here (and in other mojom files): * - consts @@ -78,6 +83,116 @@ module libcamera; uint32 height; }; +/** + * \struct IPACameraSensorInfo + * \brief Report the image sensor characteristics + * + * The structure reports image sensor characteristics used by IPA modules to + * tune their algorithms based on the image sensor model currently in use and + * its configuration. + * + * The reported information describes the sensor's intrinsics characteristics, + * such as its pixel array size and the sensor model name, as well as + * information relative to the currently configured mode, such as the produced + * image size and the bit depth of the requested image format. + * + * Instances of this structure are meant to be assembled by the CameraSensor + * class by inspecting the sensor static properties as well as information + * relative to the current configuration. + */ + +/** + * \var IPACameraSensorInfo::model + * \brief The image sensor model name + * + * The sensor model name is a free-formed string that uniquely identifies the + * sensor model. + */ + +/** + * \var IPACameraSensorInfo::bitsPerPixel + * \brief The number of bits per pixel of the image format produced by the + * image sensor + */ + +/** + * \var IPACameraSensorInfo::activeAreaSize + * \brief The size of the pixel array active area of the sensor + */ + +/** + * \var IPACameraSensorInfo::analogCrop + * \brief The portion of the pixel array active area which is read-out and + * processed + * + * The analog crop rectangle top-left corner is defined as the displacement + * from the top-left corner of the pixel array active area. The rectangle + * horizontal and vertical sizes define the portion of the pixel array which + * is read-out and provided to the sensor's internal processing pipeline, before + * any pixel sub-sampling method, such as pixel binning, skipping and averaging + * take place. + */ + +/** + * \var IPACameraSensorInfo::outputSize + * \brief The size of the images produced by the camera sensor + * + * The output image size defines the horizontal and vertical sizes of the images + * produced by the image sensor. The output image size is defined as the end + * result of the sensor's internal image processing pipeline stages, applied on + * the pixel array portion defined by the analog crop rectangle. Each image + * processing stage that performs pixel sub-sampling techniques, such as pixel + * binning or skipping, or perform any additional digital scaling concur in the + * definition of the output image size. + */ + +/** + * \var IPACameraSensorInfo::pixelRate + * \brief The number of pixels produced in a second + * + * To obtain the read-out time in seconds of a full line: + * + * \verbatim + lineDuration(s) = lineLength(pixels) / pixelRate(pixels per second) + \endverbatim + */ + +/** + * \var IPACameraSensorInfo::lineLength + * \brief Total line length in pixels + * + * The total line length in pixel clock periods, including blanking. + */ + +/** + * \var IPACameraSensorInfo::minFrameLength + * \brief The minimum allowable frame length in units of lines + * + * The sensor frame length comprises of active output lines and blanking lines + * in a frame. The minimum frame length value dictates the minimum allowable + * frame duration of the sensor mode. + * + * To obtain the minimum frame duration: + * + * \verbatim + frameDuration(s) = minFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second) + \endverbatim + */ + +/** + * \var IPACameraSensorInfo::maxFrameLength + * \brief The maximum allowable frame length in units of lines + * + * The sensor frame length comprises of active output lines and blanking lines + * in a frame. The maximum frame length value dictates the maximum allowable + * frame duration of the sensor mode. + * + * To obtain the maximum frame duration: + * + * \verbatim + frameDuration(s) = maxFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second) + \endverbatim + */ struct IPACameraSensorInfo { string model; @@ -94,35 +209,88 @@ struct IPACameraSensorInfo { uint32 maxFrameLength; }; +/** + * \struct IPABuffer + * \brief Buffer information for the IPA interface + * + * The IPABuffer structure associates buffer memory with a unique ID. It is + * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which + * buffers will be identified by their ID in the IPA interface. + */ + +/** + * \var IPABuffer::id + * \brief The buffer unique ID + * + * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs + * are chosen by the pipeline handler to fulfil the following constraints: + * + * - IDs shall be positive integers different than zero + * - IDs shall be unique among all mapped buffers + * + * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are + * freed and may be reused for new buffer mappings. + */ + +/** + * \var IPABuffer::planes + * \brief The buffer planes description + * + * Stores the dmabuf handle and length for each plane of the buffer. + */ struct IPABuffer { uint32 id; [hasFd] array planes; }; +/** + * \struct IPASettings + * \brief IPA interface initialization settings + * + * The IPASettings structure stores data passed to the IPAInterface::init() + * function. The data contains settings that don't depend on a particular camera + * or pipeline configuration and are valid for the whole life time of the IPA + * interface. + */ + +/** + * \var IPASettings::configurationFile + * \brief The name of the IPA configuration file + * + * This field may be an empty string if the IPA doesn't require a configuration + * file. + */ + +/** + * \var IPASettings::sensorModel + * \brief The sensor model name + * + * Provides the sensor model name to the IPA. + */ struct IPASettings { string configurationFile; string sensorModel; }; -struct IPAStream { - uint32 pixelFormat; - Size size; -}; - /** - * \fn IPAInterface::init() - * \brief Initialise the IPAInterface - * \param[in] settings The IPA initialization settings + * \struct IPAStream + * \brief Stream configuration for the IPA interface * - * This function initializes the IPA interface. It shall be called before any - * other function of the IPAInterface. The \a settings carry initialization - * parameters that are valid for the whole life time of the IPA interface. + * The IPAStream structure stores stream configuration parameters needed by the + * IPAInterface::configure() method. It mirrors the StreamConfiguration class + * that is not suitable for this purpose due to not being serializable. */ /** - * \fn IPAInterface::stop() - * \brief Stop the IPA - * - * This method informs the IPA module that the camera is stopped. The IPA module - * shall release resources prepared in start(). + * \var IPAStream::pixelFormat + * \brief The stream pixel format + */ + +/** + * \var IPAStream::size + * \brief The stream size in pixels */ +struct IPAStream { + uint32 pixelFormat; + Size size; +}; diff --git a/src/libcamera/ipa/core_ipa_interface.cpp b/src/libcamera/ipa/core_ipa_interface.cpp deleted file mode 100644 index 6ab689cd..00000000 --- a/src/libcamera/ipa/core_ipa_interface.cpp +++ /dev/null @@ -1,199 +0,0 @@ -/* SPDX-License-Identifier: LGPL-2.1-or-later */ -/* - * Copyright (C) 2021, Google Inc. - * - * core_ipa_interface.cpp - Docs file for core.mojom generated header - */ - -namespace libcamera { - -/** - * \file core_ipa_interface.h - * \brief Core IPA inteface - */ - -/** - * \struct IPABuffer - * \brief Buffer information for the IPA interface - * - * The IPABuffer structure associates buffer memory with a unique ID. It is - * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which - * buffers will be identified by their ID in the IPA interface. - */ - -/** - * \var IPABuffer::id - * \brief The buffer unique ID - * - * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs - * are chosen by the pipeline handler to fulfil the following constraints: - * - * - IDs shall be positive integers different than zero - * - IDs shall be unique among all mapped buffers - * - * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are - * freed and may be reused for new buffer mappings. - */ - -/** - * \var IPABuffer::planes - * \brief The buffer planes description - * - * Stores the dmabuf handle and length for each plane of the buffer. - */ - -/** - * \struct IPASettings - * \brief IPA interface initialization settings - * - * The IPASettings structure stores data passed to the IPAInterface::init() - * function. The data contains settings that don't depend on a particular camera - * or pipeline configuration and are valid for the whole life time of the IPA - * interface. - */ - -/** - * \var IPASettings::configurationFile - * \brief The name of the IPA configuration file - * - * This field may be an empty string if the IPA doesn't require a configuration - * file. - */ - -/** - * \var IPASettings::sensorModel - * \brief The sensor model name - * - * Provides the sensor model name to the IPA. - */ - -/** - * \struct IPAStream - * \brief Stream configuration for the IPA interface - * - * The IPAStream structure stores stream configuration parameters needed by the - * IPAInterface::configure() method. It mirrors the StreamConfiguration class - * that is not suitable for this purpose due to not being serializable. - */ - -/** - * \var IPAStream::pixelFormat - * \brief The stream pixel format - */ - -/** - * \var IPAStream::size - * \brief The stream size in pixels - */ - -/** - * \struct IPACameraSensorInfo - * \brief Report the image sensor characteristics - * - * The structure reports image sensor characteristics used by IPA modules to - * tune their algorithms based on the image sensor model currently in use and - * its configuration. - * - * The reported information describes the sensor's intrinsics characteristics, - * such as its pixel array size and the sensor model name, as well as - * information relative to the currently configured mode, such as the produced - * image size and the bit depth of the requested image format. - * - * Instances of this structure are meant to be assembled by the CameraSensor - * class by inspecting the sensor static properties as well as information - * relative to the current configuration. - */ - -/** - * \var IPACameraSensorInfo::model - * \brief The image sensor model name - * - * The sensor model name is a free-formed string that uniquely identifies the - * sensor model. - */ - -/** - * \var IPACameraSensorInfo::bitsPerPixel - * \brief The number of bits per pixel of the image format produced by the - * image sensor - */ - -/** - * \var IPACameraSensorInfo::activeAreaSize - * \brief The size of the pixel array active area of the sensor - */ - -/** - * \var IPACameraSensorInfo::analogCrop - * \brief The portion of the pixel array active area which is read-out and - * processed - * - * The analog crop rectangle top-left corner is defined as the displacement - * from the top-left corner of the pixel array active area. The rectangle - * horizontal and vertical sizes define the portion of the pixel array which - * is read-out and provided to the sensor's internal processing pipeline, before - * any pixel sub-sampling method, such as pixel binning, skipping and averaging - * take place. - */ - -/** - * \var IPACameraSensorInfo::outputSize - * \brief The size of the images produced by the camera sensor - * - * The output image size defines the horizontal and vertical sizes of the images - * produced by the image sensor. The output image size is defined as the end - * result of the sensor's internal image processing pipeline stages, applied on - * the pixel array portion defined by the analog crop rectangle. Each image - * processing stage that performs pixel sub-sampling techniques, such as pixel - * binning or skipping, or perform any additional digital scaling concur in the - * definition of the output image size. - */ - -/** - * \var IPACameraSensorInfo::pixelRate - * \brief The number of pixels produced in a second - * - * To obtain the read-out time in seconds of a full line: - * - * \verbatim - lineDuration(s) = lineLength(pixels) / pixelRate(pixels per second) - \endverbatim - */ - -/** - * \var IPACameraSensorInfo::lineLength - * \brief Total line length in pixels - * - * The total line length in pixel clock periods, including blanking. - */ - -/** - * \var IPACameraSensorInfo::minFrameLength - * \brief The minimum allowable frame length in units of lines - * - * The sensor frame length comprises of active output lines and blanking lines - * in a frame. The minimum frame length value dictates the minimum allowable - * frame duration of the sensor mode. - * - * To obtain the minimum frame duration: - * - * \verbatim - frameDuration(s) = minFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second) - \endverbatim - */ - -/** - * \var IPACameraSensorInfo::maxFrameLength - * \brief The maximum allowable frame length in units of lines - * - * The sensor frame length comprises of active output lines and blanking lines - * in a frame. The maximum frame length value dictates the maximum allowable - * frame duration of the sensor mode. - * - * To obtain the maximum frame duration: - * - * \verbatim - frameDuration(s) = maxFrameLength(lines) * lineLength(pixels) / pixelRate(pixels per second) - \endverbatim - */ -} /* namespace libcamera */