summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--include/libcamera/ipa/core.mojom70
1 files changed, 42 insertions, 28 deletions
diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom
index b32f3093..f7f6e678 100644
--- a/include/libcamera/ipa/core.mojom
+++ b/include/libcamera/ipa/core.mojom
@@ -15,40 +15,54 @@ module libcamera;
*
* Attributes:
* - skipHeader - structs only, and only in core.mojom
- * - designate that this struct shall not have a C++ header definition
- * generated
+ * - Do not generate a C++ definition for the structure
+ * - Any type used in a mojom interface definition must have a corresponding
+ * definition in a mojom file for the code generator to accept it, except
+ * for types solely used as map/array members for which a definition is not
+ * required
+ * - This attribute allows defining a symbol for the code generator that
+ * corresponds to a libcamera type without duplicating its definition in the
+ * generated C++ headers
* - skipSerdes - structs only, and only in core.mojom
- * - designate that this struct shall not have a (de)serializer generated
- * - all fields need a (de)serializer to be defined, either hand-written
- * in ipa_data_serializer.h
+ * - All types need a (de)serializer to be defined in order to be transported
+ * over IPC. The (de)serializer can be:
+ * - Manually implemented as a template specialization in
+ * ipa_data_serializer.cpp in the libcamera sources
+ * - Generated at build time for types defined in a mojom file
+ * - This attribute instructs the build system that a (de)serializer is
+ * available for the type and there's no need to generate one
* - hasFd - struct fields or empty structs only
- * - designate that this field or empty struct contains a FileDescriptor
+ * - Designate that this field or empty struct contains a FileDescriptor
*
* Rules:
- * - Any struct that is used in a struct definition in mojom must also be
- * defined in mojom
- * - If the struct has both a definition in a C++ header and a (de)serializer
- * in ipa_data_serializer.h, then the struct shall be declared as empty,
- * with both the [skipHeader] and [skipSerdes] attributes
- * - If the struct only has a definition in a C++ header, but no
- * (de)serializer, then the struct definition should have the [skipHeader]
- * attribute
- * - Nested structures (e.g. FrameBuffer::Plane) cannot be defined in mojom.
- * - Avoid them, by defining them in a header in C++ and a (de)serializer in
- * ipa_data_serializer.h
- * - If a struct is in an array/map inside a struct, then the struct that is
- * the member of the array/map does not need a mojom definition if it is
- * defined in a C++ header.
- * - This can be used to embed nested structures. The C++ double colon is
- * replaced with a dot (e.g. FrameBuffer::Plane -> FrameBuffer.Plane)
- * - The struct must still be defined in a header in C++ and a (de)serializer
- * implemented in ipa_data_serializer.h, as it cannot be defined in mojom
- * - [skipHeader] and [skipSerdes] only work here in core.mojom.
- * - If a struct definition has [skipHeader], then the header where the
- * struct is defined must be #included in ipa_interface.h
+ * - If the type is defined in a libcamera C++ header *and* a (de)serializer is
+ * available then the type shall be declared as empty with both attributes
+ * associated and specified as: [skipHeader, skipSerdes]
+ * - Example: [skipHeader, skipSerdes] ControlList {};
+ * - If the type is defined in libcamera but no (de)serializer is available
+ * then the type definition in the core.mojom file should have the
+ * [skipHeader] attribute only
+ * - A (de)serializer will be generated for the type
+ * - If a type definition has [skipHeader], then the header where the type is
+ * defined must be included in ipa_interface.h
+ * - Types that are solely used as array/map members do not require a mojom
+ * definition if one exists in libcamera
+ * - Nested types (e.g. FrameBuffer::Plane) cannot be defined in mojom
+ * - If used in mojom, the nested type shall be defined in a C++ header
+ * and a (de)serializer shall be provided
+ * - Nested types can only be used as array/map members
+ * - When using the type, the C++ namespace separator :: is replaced with a
+ * dot
+ * - In example, to use the FrameBuffer::Plane type in mojom:
+ * - Provide a definition of the FrameBuffer::Plane type in a C++ header
+ * - Include the header in ipa_interface.h
+ * - Provide a (de)serializer implementation ipa_data_serializer.cpp
+ * - In mojom, reference the type as FrameBuffer.Plane and only as map/array
+ * member
+ * - [skipHeader] and [skipSerdes] only work here in core.mojom
* - If a field in a struct has a FileDescriptor, but is not explicitly
* defined so in mojom, then the field must be marked with the [hasFd]
- * attribute.
+ * attribute
*
* \todo Generate documentation from Doxygen comments in .mojom files
* \todo Figure out how to keep the skipHeader structs in sync with their