{"id":13118,"url":"https://patchwork.libcamera.org/api/1.1/patches/13118/?format=json","web_url":"https://patchwork.libcamera.org/patch/13118/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20210726143549.23509-1-jacopo@jmondi.org>","date":"2021-07-26T14:35:49","name":"[libcamera-devel,v3] ipa: core.mojom: Rework core file documentation","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"3030df6735e618cbf188c99c6c778b16913775bc","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/1.1/people/3/?format=json","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/13118/mbox/","series":[{"id":2278,"url":"https://patchwork.libcamera.org/api/1.1/series/2278/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=2278","date":"2021-07-26T14:35:49","name":"[libcamera-devel,v3] ipa: core.mojom: Rework core file documentation","version":3,"mbox":"https://patchwork.libcamera.org/series/2278/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/13118/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/13118/checks/","tags":{},"headers":{"Return-Path":"","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 1CEA0C0109\n\tfor ;\n\tMon, 26 Jul 2021 14:35:07 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 94BDA687BE;\n\tMon, 26 Jul 2021 16:35:06 +0200 (CEST)","from relay7-d.mail.gandi.net (relay7-d.mail.gandi.net\n\t[217.70.183.200])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 9512F687AF\n\tfor ;\n\tMon, 26 Jul 2021 16:35:05 +0200 (CEST)","(Authenticated sender: jacopo@jmondi.org)\n\tby relay7-d.mail.gandi.net (Postfix) with ESMTPSA id EB2952000F;\n\tMon, 26 Jul 2021 14:35:04 +0000 (UTC)"],"From":"Jacopo Mondi ","To":"libcamera-devel@lists.libcamera.org","Date":"Mon, 26 Jul 2021 16:35:49 +0200","Message-Id":"<20210726143549.23509-1-jacopo@jmondi.org>","X-Mailer":"git-send-email 2.32.0","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH v3] 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":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"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 comments to match the most recent IPA/IPC\ninterface definition and generation mechanism.\n\nSigned-off-by: Jacopo Mondi \n---\nv2-v3:\n- Address Paul's comment:\n - s/[Mojo core|build system]/code generator/\n - Swap points in skipSerdes description to make clear the flag instruct\n the code generator not to generate a deserializer\n - Clarify that nested types can *solely* be used as map/array members\n\nv1->v2:\n- Address Paul's comment and clarify points that were not clear to me when I\n wrote v1 :)\n - (de)serializers implementations go in ipa_data_serializer.cpp\n - types used as array/map members do not require a mojom definition\n - remove duplications\n - s/the library/libcamera\n- While at it, make all statements start with a capital letter and end without a\n full-stop.\n---\n\n include/libcamera/ipa/core.mojom | 68 +++++++++++++++++++-------------\n 1 file changed, 41 insertions(+), 27 deletions(-)\n\n--\n2.32.0","diff":"diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom\nindex b32f30939454..2e1835c6ec84 100644\n--- a/include/libcamera/ipa/core.mojom\n+++ b/include/libcamera/ipa/core.mojom\n@@ -15,40 +15,54 @@ 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 code generator to accept it, except for\n+ * types solely used as map/array members for which a definition is not\n+ * required\n+ * - This attribute allows defining a symbol for the code generator that\n+ * corresponds to a libcamera type without duplicating its definition in the\n+ * 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+ * - 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 as a template specialization in\n+ * ipa_data_serializer.cpp in the libcamera sources\n+ * - Generated at build time for types defined in a mojo interfaces\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+ * - 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 libcamera C++ header *and* a (de)serializer is\n+ * available then the type shall be declared as empty with both attributes\n+ * associated and specified as: [skipHeader, skipSerdes]\n+ * - Example: [skipHeader, skipSerdes] ControlList {};\n+ * - If the type is defined in libcamera but no (de)serializer is available\n+ * then the type definition in the core.mojom file should have the\n+ * [skipHeader] attribute only\n+ * - A (de)serializer will be generated for the type\n+ * - If a type definition has [skipHeader], then the header where the type is\n+ * defined must be included in ipa_interface.h\n+ * - Types that are solely contained in an array/map do not require a mojom\n+ * definition if one exists in libcamera\n+ * - Nested types (e.g. FrameBuffer::Plane) cannot be defined in mojom\n+ * - If used in mojom, the nested type shall be defined in a C++ header\n+ * and a (de)serializer shall be provided\n+ * - Nested types can only be used as part of array/map containers\n+ * - When using the type, the C++ namespace separator :: is replaced with a\n+ * dot\n+ * - In example, to use the FrameBuffer::Plane type in mojom:\n+ * - Provide a definition of the FrameBuffer::Plane type in a C++ header\n+ * - Include the header in ipa_interface.h\n+ * - Provide a (de)serializer implementation ipa_data_serializer.cpp\n+ * - In mojom, reference the type as FrameBuffer.Plane and only as map/array\n+ * member\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+ * 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","prefixes":["libcamera-devel","v3"]}