ipa: Define serialized controls

Define data structures to be used during interaction between IPA modules
and pipeline handlers to serialize control lists and control info maps.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

4 files changed, 242 insertions, 0 deletions

diff --git a/include/ipa/ipa_controls.h b/include/ipa/ipa_controls.h
new file mode 100644
index 00000000..de3a017b
--- /dev/null
+++ b/include/ipa/ipa_controls.h
@@ -0,0 +1,54 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * ipa_controls.h - IPA Control handling
+ */
+#ifndef __LIBCAMERA_IPA_CONTROLS_H__
+#define __LIBCAMERA_IPA_CONTROLS_H__
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define IPA_CONTROLS_FORMAT_VERSION	1
+
+struct ipa_controls_header {
+	uint32_t version;
+	uint32_t handle;
+	uint32_t entries;
+	uint32_t size;
+	uint32_t data_offset;
+	uint32_t reserved[3];
+};
+
+struct ipa_control_value_entry {
+	uint32_t id;
+	uint32_t type;
+	uint32_t count;
+	uint32_t offset;
+};
+
+struct ipa_control_range_entry {
+	uint32_t id;
+	uint32_t type;
+	uint32_t offset;
+	uint32_t padding[1];
+};
+
+union ipa_control_value_data {
+	bool b;
+	int32_t i32;
+	int64_t i64;
+};
+
+struct ipa_control_range_data {
+	union ipa_control_value_data min;
+	union ipa_control_value_data max;
+};
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __LIBCAMERA_IPA_CONTROLS_H__ */
diff --git a/include/ipa/meson.build b/include/ipa/meson.build
index a0ce96ba..695a4183 100644
--- a/include/ipa/meson.build
+++ b/include/ipa/meson.build
@@ -1,4 +1,5 @@
 libcamera_ipa_api = files([
+    'ipa_controls.h',
     'ipa_interface.h',
     'ipa_module_info.h',
 ])
diff --git a/src/libcamera/ipa_controls.cpp b/src/libcamera/ipa_controls.cpp
new file mode 100644
index 00000000..ed12830c
--- /dev/null
+++ b/src/libcamera/ipa_controls.cpp
@@ -0,0 +1,186 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * ipa_controls.h - IPA control handling
+ */
+
+/**
+ * \file ipa_controls.h
+ * \brief Type definitions for serialized controls
+ *
+ * This file defines binary formats to store ControlList and ControlInfoMap
+ * instances in contiguous, self-contained memory areas called control packets.
+ * It describes the layout of the packets through a set of C structures. These
+ * formats shall be used when serializing ControlList and ControlInfoMap to
+ * transfer them through the IPA C interface and IPA IPC transports.
+ *
+ * A control packet contains a list of entries, each of them describing a single
+ * control range or control value. The packet starts with a fixed-size header
+ * described by the ipa_controls_header structure, followed by an array of
+ * fixed-size entries. Each entry is associated with data, stored either
+ * directly in the entry, or in a data section after the entries array.
+ *
+ * The following diagram describes the layout of the ControlList packet.
+ *
+ * ~~~~
+ *           +-------------------------+    .                      .
+ *  Header / | ipa_controls_header     |    |                      |
+ *         | |                         |    |                      |
+ *         \ |                         |    |                      |
+ *           +-------------------------+    |                      |
+ *         / | ipa_control_value_entry |    | hdr.data_offset      |
+ *         | | #0                      |    |                      |
+ * Control | +-------------------------+    |                      |
+ *   value | | ...                     |    |                      |
+ * entries | +-------------------------+    |                      |
+ *         | | ipa_control_value_entry |    |             hdr.size |
+ *         \ | #hdr.entries - 1        |    |                      |
+ *           +-------------------------+    |                      |
+ *           | empty space (optional)  |    |                      |
+ *           +-------------------------+ <--´  .                   |
+ *         / | ...                     |       | entry[n].offset   |
+ *    Data | | ...                     |       |                   |
+ * section | | value data for entry #n | <-----´                   |
+ *         \ | ...                     |                           |
+ *           +-------------------------+                           |
+ *           | empty space (optional)  |                           |
+ *           +-------------------------+ <-------------------------´
+ * ~~~~
+ *
+ * The packet header contains the size of the packet, the number of entries, and
+ * the offset from the beginning of the packet to the data section. The packet
+ * entries array immediately follows the header. The data section starts at the
+ * offset ipa_controls_header::data_offset from the beginning of the packet, and
+ * shall be aligned to a multiple of 8 bytes.
+ *
+ * Entries are described by the ipa_control_value_entry structure. They contain
+ * the numerical ID of the control, its type, and the number of control values.
+ *
+ * The control values are stored in the data section in the platform's native
+ * format. The ipa_control_value_entry::offset field stores the offset from the
+ * beginning of the data section to the values.
+ *
+ * All control values in the data section shall be stored in the same order as
+ * the respective control entries, shall be aligned to a multiple of 8 bytes,
+ * and shall be contiguous in memory.
+ *
+ * Empty spaces may be present between the end of the entries array and the
+ * data section, and after the data section. They shall be ignored when parsing
+ * the packet.
+ *
+ * The following diagram describes the layout of the ControlInfoMap packet.
+ *
+ * ~~~~
+ *           +-------------------------+    .                      .
+ *  Header / | ipa_controls_header     |    |                      |
+ *         | |                         |    |                      |
+ *         \ |                         |    |                      |
+ *           +-------------------------+    |                      |
+ *         / | ipa_control_range_entry |    | hdr.data_offset      |
+ *         | | #0                      |    |                      |
+ * Control | +-------------------------+    |                      |
+ *   range | | ...                     |    |                      |
+ * entries | +-------------------------+    |                      |
+ *         | | ipa_control_range_entry |    |             hdr.size |
+ *         \ | #hdr.entries - 1        |    |                      |
+ *           +-------------------------+    |                      |
+ *           | empty space (optional)  |    |                      |
+ *           +-------------------------+ <--´  .                   |
+ *         / | ...                     |       | entry[n].offset   |
+ *    Data | | ...                     |       |                   |
+ * section | | range data for entry #n | <-----´                   |
+ *         \ | ...                     |                           |
+ *           +-------------------------+                           |
+ *           | empty space (optional)  |                           |
+ *           +-------------------------+ <-------------------------´
+ * ~~~~
+ *
+ * The packet header is identical to the ControlList packet header.
+ *
+ * Entries are described by the ipa_control_range_entry structure. They contain
+ * the numerical ID and type of the control. The control range data is stored
+ * in the data section as described by the ipa_control_range_data structure.
+ * The ipa_control_range_entry::offset field stores the offset from the
+ * beginning of the data section to the range data.
+ *
+ * Range data in the data section shall be stored in the same order as the
+ * entries array, shall be aligned to a multiple of 8 bytes, and shall be
+ * contiguous in memory.
+ *
+ * As for the ControlList packet, empty spaces may be present between the end of
+ * the entries array and the data section, and after the data section. They
+ * shall be ignored when parsing the packet.
+ */
+
+/**
+ * \def IPA_CONTROLS_FORMAT_VERSION
+ * \brief The current control serialization format version
+ */
+
+/**
+ * \struct ipa_controls_header
+ * \brief Serialized control packet header
+ * \var ipa_controls_header::version
+ * Control packet format version number (shall be IPA_CONTROLS_FORMAT_VERSION)
+ * \var ipa_controls_header::handle
+ * For ControlInfoMap packets, this field contains a unique non-zero handle
+ * generated when the ControlInfoMap is serialized. For ControlList packets,
+ * this field contains the handle of the corresponding ControlInfoMap.
+ * \var ipa_controls_header::entries
+ * Number of entries in the packet
+ * \var ipa_controls_header::size
+ * The total packet size in bytes
+ * \var ipa_controls_header::data_offset
+ * Offset in bytes from the beginning of the packet of the data section start
+ * \var ipa_controls_header::reserved
+ * Reserved for future extensions
+ */
+
+/**
+ * \struct ipa_control_value_entry
+ * \brief Description of a serialized ControlValue entry
+ * \var ipa_control_value_entry::id
+ * The numerical ID of the control
+ * \var ipa_control_value_entry::type
+ * The type of the control (defined by enum ControlType)
+ * \var ipa_control_value_entry::count
+ * The number of control array entries for array controls (1 otherwise)
+ * \var ipa_control_value_entry::offset
+ * The offset in bytes from the beginning of the data section to the control
+ * value data (shall be a multiple of 8 bytes).
+ */
+
+/**
+ * \struct ipa_control_range_entry
+ * \brief Description of a serialized ControlRange entry
+ * \var ipa_control_range_entry::id
+ * The numerical ID of the control
+ * \var ipa_control_range_entry::type
+ * The type of the control (defined by enum ControlType)
+ * \var ipa_control_range_entry::offset
+ * The offset in bytes from the beginning of the data section to the control
+ * range data (shall be a multiple of 8 bytes)
+ * \var ipa_control_range_entry::padding
+ * Padding bytes (shall be set to 0)
+ */
+
+/**
+ * \union ipa_control_value_data
+ * \brief Serialized control value
+ * \var ipa_control_value_data::b
+ * Value for ControlTypeBool controls
+ * \var ipa_control_value_data::i32
+ * Value for ControlTypeInteger32 controls
+ * \var ipa_control_value_data::i64
+ * Value for ControlTypeInteger64 controls
+ */
+
+/**
+ * \struct ipa_control_range_data
+ * \brief Serialized control range
+ * \var ipa_control_range_data::min
+ * The control minimum value
+ * \var ipa_control_range_data::max
+ * The control maximum value
+ */
diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
index afbca769..be0cd53f 100644
--- a/src/libcamera/meson.build
+++ b/src/libcamera/meson.build
@@ -14,6 +14,7 @@ libcamera_sources = files([
     'event_notifier.cpp',
     'formats.cpp',
     'geometry.cpp',
+    'ipa_controls.cpp',
     'ipa_interface.cpp',
     'ipa_manager.cpp',
     'ipa_module.cpp',