Patch Detail
Show a patch.
GET /api/patches/12962/?format=api
{ "id": 12962, "url": "https://patchwork.libcamera.org/api/patches/12962/?format=api", "web_url": "https://patchwork.libcamera.org/patch/12962/", "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": "<20210715153200.63805-1-jacopo@jmondi.org>", "date": "2021-07-15T15:32:00", "name": "[libcamera-devel] ipa: core.mojom: Rework core file documentation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "d6af4a5efd40703e342e84cea5928bb9dd4e3a0b", "submitter": { "id": 3, "url": "https://patchwork.libcamera.org/api/people/3/?format=api", "name": "Jacopo Mondi", "email": "jacopo@jmondi.org" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/12962/mbox/", "series": [ { "id": 2238, "url": "https://patchwork.libcamera.org/api/series/2238/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=2238", "date": "2021-07-15T15:32:00", "name": "[libcamera-devel] ipa: core.mojom: Rework core file documentation", "version": 1, "mbox": "https://patchwork.libcamera.org/series/2238/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/12962/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/12962/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 1DE34C3226\n\tfor <parsemail@patchwork.libcamera.org>;\n\tThu, 15 Jul 2021 15:31:22 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id C300F68539;\n\tThu, 15 Jul 2021 17:31:21 +0200 (CEST)", "from relay10.mail.gandi.net (relay10.mail.gandi.net\n\t[217.70.178.230])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 400406059F\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 15 Jul 2021 17:31:20 +0200 (CEST)", "(Authenticated sender: jacopo@jmondi.org)\n\tby relay10.mail.gandi.net (Postfix) with ESMTPSA id 83B1124000D;\n\tThu, 15 Jul 2021 15:31:19 +0000 (UTC)" ], "From": "Jacopo Mondi <jacopo@jmondi.org>", "To": "libcamera-devel@lists.libcamera.org", "Date": "Thu, 15 Jul 2021 17:32:00 +0200", "Message-Id": "<20210715153200.63805-1-jacopo@jmondi.org>", "X-Mailer": "git-send-email 2.32.0", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "Subject": "[libcamera-devel] [PATCH] ipa: core.mojom: Rework core file\n\tdocumentation", "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>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "The comment block at the beginning of the core.mojom file is meant to\nprovide an overview of how to use libcamera defined types in the definition\nof mojom interfaces.\n\nAs the IPA/IPC interface definition mechanism evolved, the documentation\nhas not been updated accordingly.\n\nUpdate the file comment to match the most recent of th IPA/IPC\ninterface definition and generation mechanism.\n\nSigned-off-by: Jacopo Mondi <jacopo@jmondi.org>\n---\n include/libcamera/ipa/core.mojom | 60 +++++++++++++++++++-------------\n 1 file changed, 35 insertions(+), 25 deletions(-)", "diff": "diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom\nindex b32f30939454..d2017369b597 100644\n--- a/include/libcamera/ipa/core.mojom\n+++ b/include/libcamera/ipa/core.mojom\n@@ -15,37 +15,47 @@ module libcamera;\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+ * - do not generate a C++ definition for the structure\n+ * - any type used in a mojom interface definition must have a corresponding\n+ * definition in a mojo file for the Mojo core to accept it\n+ * - this attribute allows to define a symbol for the Mojo core that\n+ * corresponds to a library-defined type without duplicating its definition\n+ * in the generated C++ headers\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+ * - do not generate a (de)serializer for the structure\n+ * - all types need a (de)serializer to be defined in order to be transported\n+ * over the IPA protocol. The (de)serializer can be:\n+ * - manually implemented in the core library as in example the\n+ * ControlSerializer class that handles libcamera control-related types\n+ * - provided as a template specialization as done in ipa_data_serializer.h\n+ * for POD types and C++ containers\n+ * - generated at build time for types defined in a mojo interfaces\n+ * definition\n+ * - this attribute instructs the build system that a (de)serializer is\n+ * available for the type and there's no need to generate one\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+ * - If the type is defined in a library C++ header and a (de)serializer is\n+ * available, either manually written in the library or in\n+ * ipa_data_serializer.h, then the struct shall be declared as empty,\n+ * with both the [skipHeader] and [skipSerdes] attributes associated\n+ * - If the type is defined in the library but no (de)serializer is available\n+ * then the type definition in the core.mojom file should have the\n+ * [skipHeader] attribute only\n+ * - If a type definition has [skipHeader], then the header where the type is\n+ * defined must be included in ipa_interface.h\n+ * - Nested types (e.g. FrameBuffer::Plane) cannot be directly defined in mojom\n+ * - Avoid them, by defining the nested type in a C++ header and provide a\n+ * (de)serializer\n+ * - The C++ namespace separator :: is replaced with a dot\n+ * - In example, to refer to FrameBuffer::Plane provide a definition of the\n+ * Plane type in a C++ header to be included, provide a deserializer and\n+ * reference it as FrameBuffer.Plane\n+ * - Types that are contained in an array/map do not require a mojom definition\n+ * if one exists in the library.\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 in 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", "prefixes": [ "libcamera-devel" ] }