[libcamera-devel] [PATCH v5 15/23] ipa: Add core.mojom

[Paul Elder]

Add a base mojom file to contain empty mojom definitions of libcamera
objects, as well as documentation for the IPA interfaces that need to be
defined in the mojom files.

Signed-off-by: Paul Elder <paul.elder at ideasonboard.com>

---
Changes in v5:
- add todo for defining some libcamera ipa structs in mojom
- remove ipa_mojom_core from dependencies of everything in the generator
  stage
- add documentation for the base IPA functions (init, stop, start)

Changes in v4:
- move docs to IPA guide

Changes in v3:
- add doc that structs need to be defined
- add doc to recommend namespacing
- change indentation
- add requirement that base controls *must* be defined in
  libcamera::{pipeline_name}::Controls

New in v2
---
 include/libcamera/ipa/core.mojom       | 48 ++++++++++++++++++++++++++
 include/libcamera/ipa/meson.build      | 14 +++++++-
 src/libcamera/proxy/meson.build        |  4 +--
 src/libcamera/proxy/worker/meson.build |  4 +--
 4 files changed, 65 insertions(+), 5 deletions(-)
 create mode 100644 include/libcamera/ipa/core.mojom

diff --git a/include/libcamera/ipa/core.mojom b/include/libcamera/ipa/core.mojom
new file mode 100644
index 00000000..95d12b63
--- /dev/null
+++ b/include/libcamera/ipa/core.mojom
@@ -0,0 +1,48 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+/*
+ * Any libcamera objects that are used by any interfaces that aren't defined
+ * in mojom must be declared here, and a (de)serializer be implemented as a
+ * template specialization of IPADataSerializer. In addition, the corresponding
+ * header file (or forward-declarations) must be included in {pipeline_name}.h.
+ *
+ * For libcamera types, the [hasFd] attribute is needed to notify the compiler
+ * that the struct embeds a FileDescriptor.
+ */
+struct CameraSensorInfo {};
+struct ControlInfoMap {};
+struct ControlList {};
+struct FileDescriptor {};
+
+/* \todo Define these structures fully in mojom. */
+[hasFd] struct IPABuffer {};
+struct IPASettings {};
+struct IPAStream {};
+
+/**
+ * \fn init()
+ * \brief Initialise the IPAInterface
+ * \param[in] settings The IPA initialization settings
+ *
+ * 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.
+ */
+
+/**
+ * \fn start()
+ * \brief Start the IPA
+ *
+ * This method informs the IPA module that the camera is about to be started.
+ * The IPA module shall prepare any resources it needs to operate.
+ *
+ * \return 0 on success or a negative error code otherwise
+ */
+
+/**
+ * \fn 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().
+ */
diff --git a/include/libcamera/ipa/meson.build b/include/libcamera/ipa/meson.build
index d7a2b6b2..087f5bbd 100644
--- a/include/libcamera/ipa/meson.build
+++ b/include/libcamera/ipa/meson.build
@@ -13,6 +13,17 @@ install_headers(libcamera_ipa_headers,
 # Prepare IPA/IPC generation components
 #
 
+core_mojom_file = 'core.mojom'
+ipa_mojom_core = custom_target(core_mojom_file.split('.')[0] + '_mojom_module',
+                               input : core_mojom_file,
+                               output : core_mojom_file + '-module',
+                               command : [
+                                   mojom_parser,
+                                   '--output-root', meson.build_root(),
+                                   '--input-root', meson.source_root(),
+                                   '--mojoms', '@INPUT@'
+                               ])
+
 ipa_mojom_files = []
 
 ipa_mojoms = []
@@ -30,6 +41,7 @@ foreach file : ipa_mojom_files
     mojom = custom_target(file.split('.')[0] + '_mojom_module',
                           input : file,
                           output : file + '-module',
+                          depends : ipa_mojom_core,
                           command : [
                               mojom_parser,
                               '--output-root', meson.build_root(),
@@ -68,7 +80,7 @@ foreach file : ipa_mojom_files
     # ipa_proxy_{pipeline}.h
     proxy_header = custom_target(name + '_proxy_h',
                                  input : mojom,
-                                 output : 'ipa_proxy_' + name + '.h',
+                                 output : name + '_ipa_proxy.h',
                                  depends : mojom_templates,
                                  command : [
                                      mojom_generator, 'generate',
diff --git a/src/libcamera/proxy/meson.build b/src/libcamera/proxy/meson.build
index 5965589f..a3f6b223 100644
--- a/src/libcamera/proxy/meson.build
+++ b/src/libcamera/proxy/meson.build
@@ -4,8 +4,8 @@
 foreach mojom : ipa_mojoms
     proxy = custom_target(mojom['name'] + '_proxy_cpp',
                           input : mojom['mojom'],
-                          output : 'ipa_proxy_' + mojom['name'] + '.cpp',
-                          depends : [mojom_templates],
+                          output : mojom['name'] + '_ipa_proxy.cpp',
+                          depends : mojom_templates,
                           command : [
                               mojom_generator, 'generate',
                               '-g', 'libcamera',
diff --git a/src/libcamera/proxy/worker/meson.build b/src/libcamera/proxy/worker/meson.build
index f3129b76..cc55078f 100644
--- a/src/libcamera/proxy/worker/meson.build
+++ b/src/libcamera/proxy/worker/meson.build
@@ -6,8 +6,8 @@ proxy_install_dir = join_paths(get_option('libexecdir'), 'libcamera')
 foreach mojom : ipa_mojoms
     worker = custom_target(mojom['name'] + '_proxy_worker',
                            input : mojom['mojom'],
-                           output : 'ipa_proxy_' + mojom['name'] + '_worker.cpp',
-                           depends : [mojom_templates],
+                           output : mojom['name'] + '_ipa_proxy_worker.cpp',
+                           depends : mojom_templates,
                            command : [
                                mojom_generator, 'generate',
                                '-g', 'libcamera',
-- 
2.27.0