Patch Detail
Show a patch.
GET /api/patches/11221/?format=api
{ "id": 11221, "url": "https://patchwork.libcamera.org/api/patches/11221/?format=api", "web_url": "https://patchwork.libcamera.org/patch/11221/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20210211071805.34963-11-paul.elder@ideasonboard.com>", "date": "2021-02-11T07:18:05", "name": "[libcamera-devel,v7,10/10] ipa: Add core.mojom", "commit_ref": null, "pull_url": null, "state": "changes-requested", "archived": false, "hash": "9a2c4f46db3945cb80d121a16b404d5737c79766", "submitter": { "id": 17, "url": "https://patchwork.libcamera.org/api/people/17/?format=api", "name": "Paul Elder", "email": "paul.elder@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/11221/mbox/", "series": [ { "id": 1675, "url": "https://patchwork.libcamera.org/api/series/1675/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=1675", "date": "2021-02-11T07:17:55", "name": "IPA isolation: Part 1: Core components", "version": 7, "mbox": "https://patchwork.libcamera.org/series/1675/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/11221/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/11221/checks/", "tags": {}, "headers": { "Return-Path": "<libcamera-devel-bounces@lists.libcamera.org>", "X-Original-To": "parsemail@patchwork.libcamera.org", "Delivered-To": "parsemail@patchwork.libcamera.org", "Received": [ "from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 54B80BD162\n\tfor <parsemail@patchwork.libcamera.org>;\n\tThu, 11 Feb 2021 07:18:43 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 234956168F;\n\tThu, 11 Feb 2021 08:18:43 +0100 (CET)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id D118D61660\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 11 Feb 2021 08:18:41 +0100 (CET)", "from pyrite.rasen.tech (unknown\n\t[IPv6:2400:4051:61:600:2c71:1b79:d06d:5032])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id B5C22BB8;\n\tThu, 11 Feb 2021 08:18:39 +0100 (CET)" ], "Authentication-Results": "lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"L5Dn1T0H\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1613027921;\n\tbh=JrHEXTTy8EzMJehdjnoT5YgW9scmIcVaJclpOwScd5Q=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=L5Dn1T0HhkIHDMZsg4kI91wT9VqXEnCu1KDF6Vx87FCsEBxmi8QcF6w2Rl4RE2WDG\n\tfphl0aaXlwFYBtpxK0JuoU0colcD5I4hjnSd1B6EF1AmRXwEKEgGma0nJEP/PxTGi0\n\tmdtgI1awCOmhq+q9n2Sl5rRuUjbHLteHSpxxVo8I=", "From": "Paul Elder <paul.elder@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Thu, 11 Feb 2021 16:18:05 +0900", "Message-Id": "<20210211071805.34963-11-paul.elder@ideasonboard.com>", "X-Mailer": "git-send-email 2.27.0", "In-Reply-To": "<20210211071805.34963-1-paul.elder@ideasonboard.com>", "References": "<20210211071805.34963-1-paul.elder@ideasonboard.com>", "MIME-Version": "1.0", "Subject": "[libcamera-devel] [PATCH v7 10/10] ipa: Add core.mojom", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Content-Type": "text/plain; charset=\"utf-8\"", "Content-Transfer-Encoding": "base64", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "Add a base mojom file to contain empty mojom definitions of libcamera\nobjects, as well as documentation for the IPA interfaces that need to be\ndefined in the mojom files.\n\nSigned-off-by: Paul Elder <paul.elder@ideasonboard.com>\nReviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>\nReviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n\n---\nChanges in v7:\n- update documentation and code for the switch from genHeader/genSerdes to\n skipHeader/skipSerdes\n- rebase on new CameraSensorInfo\n- other cosmetic changes\n\nChanges in v6:\n- expand documentation on what can and can't be done in mojom\n- add definitions for geometry.h structs, and the structs that used to\n be in ipa_interface.h, including their documentation\n- remove documentation for start()\n\nChanges in v5:\n- add todo for defining some libcamera ipa structs in mojom\n- remove ipa_mojom_core from dependencies of everything in the\n generator stage\n- add documentation for the base IPA functions (init, stop, start)\n\nChanges in v4:\n- move docs to IPA guide\n\nChanges in v3:\n- add doc that structs need to be defined\n- add doc to recommend namespacing\n- change indentation\n- add requirement that base controls *must* be defined in\n libcamera::{pipeline_name}::Controls\n\nNew in v2\n---\n include/libcamera/ipa/core.mojom | 215 +++++++++++++++++++++++++++++++\n 1 file changed, 215 insertions(+)\n create mode 100644 include/libcamera/ipa/core.mojom", "diff": "diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom\nnew file mode 100644\nindex 00000000..353eee95\n--- /dev/null\n+++ b/include/libcamera/ipa/core.mojom\n@@ -0,0 +1,215 @@\n+/* SPDX-License-Identifier: LGPL-2.1-or-later */\n+\n+/*\n+ * Things that can be defined here (and in other mojom files):\n+ * - consts\n+ * - enums\n+ * - structs\n+ *\n+ * Attributes:\n+ * - skipHeader - structs only, and only in core.mojom\n+ * - designate that this struct shall not have a C++ header definition\n+ * generated\n+ * - skipSerdes - structs only, and only in core.mojom\n+ * - designate that this struct shall not have a (de)serializer generated\n+ * - all fields need a (de)serializer to be defined, either hand-written\n+ * in ipa_data_serializer.h\n+ * - hasFd - struct fields or empty structs only\n+ * - designate that this field or empty struct contains a FileDescriptor\n+ *\n+ * Rules:\n+ * - Any struct that is used in a struct definition in mojom must also be\n+ * defined in mojom\n+ * - If the struct has both a definition in a C++ header and a (de)serializer\n+ * in ipa_data_serializer.h, then the struct shall be declared as empty,\n+ * with both the [skipHeader] and [skipSerdes] attributes\n+ * - If the struct only has a definition in a C++ header, but no\n+ * (de)serializer, then the struct definition should have the [skipHeader]\n+ * attribute\n+ * - Nested structures (e.g. FrameBuffer::Plane) cannot be defined in mojom.\n+ * - Avoid them, by defining them in a header in C++ and a (de)serializer in\n+ * ipa_data_serializer.h\n+ * - If a struct is in an array/map inside a struct, then the struct that is\n+ * the member of the array/map does not need a mojom definition if it is\n+ * defined in a C++ header.\n+ * - This can be used to embed nested structures. The C++ double colon is\n+ * replaced with a dot (e.g. FrameBuffer::Plane -> FrameBuffer.Plane)\n+ * - The struct must still be defined in a header in C++ and a (de)serializer\n+ * implemented in ipa_data_serializer.h, as it cannot be defined in mojom\n+ * - [skipHeader] and [skipSerdes] only work here in core.mojom.\n+ * - If a struct definition has [skipHeader], then the header where the\n+ * struct is defined must be #included (or the struct forward-declared) in\n+ * ipa_interface.h\n+ * - If a field in a struct has a FileDescriptor, but is not explicitly\n+ * defined so in mojom, then the field must be marked with the [hasFd]\n+ * attribute.\n+ *\n+ * \\todo Generate documentation from Doxygen comments in .mojom files\n+ * \\todo Figure out how to keep the skipHeader structs in sync with their\n+ * C++ definitions, and the skipSerdes structs in sync with their\n+ * (de)serializers\n+ */\n+[skipSerdes, skipHeader] struct ControlInfoMap {};\n+[skipSerdes, skipHeader] struct ControlList {};\n+[skipSerdes, skipHeader] struct FileDescriptor {};\n+\n+[skipHeader] struct Point {\n+\tint32 x;\n+\tint32 y;\n+};\n+\n+[skipHeader] struct Size {\n+\tuint32 width;\n+\tuint32 height;\n+};\n+\n+[skipHeader] struct SizeRange {\n+\tSize min;\n+\tSize max;\n+\tuint32 hStep;\n+\tuint32 vStep;\n+};\n+\n+[skipHeader] struct Rectangle {\n+\tint32 x;\n+\tint32 y;\n+\tuint32 width;\n+\tuint32 height;\n+};\n+\n+[skipHeader] struct CameraSensorInfo {\n+\tstring model;\n+\n+\tuint32 bitsPerPixel;\n+\n+\tSize activeAreaSize;\n+\tRectangle analogCrop;\n+\tSize outputSize;\n+\n+\tuint64 pixelRate;\n+\tuint32 lineLength;\n+\n+\tuint32 minFrameLength;\n+\tuint32 maxFrameLength;\n+};\n+\n+/**\n+ * \\struct IPABuffer\n+ * \\brief Buffer information for the IPA interface\n+ *\n+ * The IPABuffer structure associates buffer memory with a unique ID. It is\n+ * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which\n+ * buffers will be identified by their ID in the IPA interface.\n+ */\n+\n+/**\n+ * \\var IPABuffer::id\n+ * \\brief The buffer unique ID\n+ *\n+ * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs\n+ * are chosen by the pipeline handler to fulfil the following constraints:\n+ *\n+ * - IDs shall be positive integers different than zero\n+ * - IDs shall be unique among all mapped buffers\n+ *\n+ * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are\n+ * freed and may be reused for new buffer mappings.\n+ */\n+\n+/**\n+ * \\var IPABuffer::planes\n+ * \\brief The buffer planes description\n+ *\n+ * Stores the dmabuf handle and length for each plane of the buffer.\n+ */\n+\n+struct IPABuffer {\n+\tuint32 id;\n+\t[hasFd] array<FrameBuffer.Plane> planes;\n+};\n+\n+/**\n+ * \\struct IPASettings\n+ * \\brief IPA interface initialization settings\n+ *\n+ * The IPASettings structure stores data passed to the IPAInterface::init()\n+ * function. The data contains settings that don't depend on a particular camera\n+ * or pipeline configuration and are valid for the whole life time of the IPA\n+ * interface.\n+ */\n+\n+/**\n+ * \\var IPASettings::configurationFile\n+ * \\brief The name of the IPA configuration file\n+ *\n+ * This field may be an empty string if the IPA doesn't require a configuration\n+ * file.\n+ */\n+struct IPASettings {\n+\tstring configurationFile;\n+};\n+\n+/**\n+ * \\struct IPAStream\n+ * \\brief Stream configuration for the IPA interface\n+ *\n+ * The IPAStream structure stores stream configuration parameters needed by the\n+ * IPAInterface::configure() method. It mirrors the StreamConfiguration class\n+ * that is not suitable for this purpose due to not being serializable.\n+ */\n+\n+/**\n+ * \\var IPAStream::pixelFormat\n+ * \\brief The stream pixel format\n+ */\n+\n+/**\n+ * \\var IPAStream::size\n+ * \\brief The stream size in pixels\n+ */\n+struct IPAStream {\n+\tuint32 pixelFormat;\n+\tSize size;\n+};\n+\n+/**\n+ * \\class IPAInterface\n+ * \\brief C++ Interface for IPA implementation\n+ *\n+ * This pure virtual class defines a skeletal C++ API for IPA modules.\n+ * Specializations of this class must be defined in a mojom file in\n+ * include/libcamera/ipa/ (see the IPA Writers Guide for details\n+ * on how to do so).\n+ *\n+ * Due to process isolation all arguments to the IPAInterface methods and\n+ * signals may need to be transferred over IPC. The class thus uses serializable\n+ * data types only. The IPA C++ interface defines custom data structures that\n+ * mirror core libcamera structures when the latter are not suitable, such as\n+ * IPAStream to carry StreamConfiguration data.\n+ *\n+ * Custom data structures may also be defined in the mojom file, in which case\n+ * the (de)serialization will automatically be generated. If any other libcamera\n+ * structures are to be used as parameters, then a (de)serializer for them must\n+ * be implemented in IPADataSerializer.\n+ *\n+ * The pipeline handlers shall use the IPAManager to locate a compatible\n+ * IPAInterface. The interface may then be used to interact with the IPA module.\n+ */\n+\n+/**\n+ * \\fn IPAInterface::init()\n+ * \\brief Initialise the IPAInterface\n+ * \\param[in] settings The IPA initialization settings\n+ *\n+ * This function initializes the IPA interface. It shall be called before any\n+ * other function of the IPAInterface. The \\a settings carry initialization\n+ * parameters that are valid for the whole life time of the IPA interface.\n+ */\n+\n+/**\n+ * \\fn IPAInterface::stop()\n+ * \\brief Stop the IPA\n+ *\n+ * This method informs the IPA module that the camera is stopped. The IPA module\n+ * shall release resources prepared in start().\n+ */\n", "prefixes": [ "libcamera-devel", "v7", "10/10" ] }