/* SPDX-License-Identifier: LGPL-2.1-or-later */
/*
 * Copyright (C) 2019, Google Inc.
 *
 * ipa_controls.cpp - IPA control handling
 */

#include <libcamera/ipa/ipa_controls.h>

/**
 * \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 info 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_info_entry  |    | hdr.data_offset      |
 *         | | #0                      |    |                      |
 * Control | +-------------------------+    |                      |
 *    info | | ...                     |    |                      |
 * entries | +-------------------------+    |                      |
 *         | | ipa_control_info_entry  |    |             hdr.size |
 *         \ | #hdr.entries - 1        |    |                      |
 *           +-------------------------+    |                      |
 *           | empty space (optional)  |    |                      |
 *           +-------------------------+ <--´  .                   |
 *         / | ...                     |       | entry[n].offset   |
 *    Data | | ...                     |       |                   |
 * section | | info data for entry #n  | <-----´                   |
 *         \ | ...                     |                           |
 *           +-------------------------+                           |
 *           | empty space (optional)  |                           |
 *           +-------------------------+ <-------------------------´
 * ~~~~
 *
 * The packet header is identical to the ControlList packet header.
 *
 * Entries are described by the ipa_control_info_entry structure. They contain
 * the numerical ID and type of the control. The control info data is stored
 * in the data section as described by the following diagram.
 *
 * ~~~~
 *           +-------------------------+       .
 *         / | ...                     |       | entry[n].offset
 *         | +-------------------------+ <-----´
 *         | | minimum value (#n)      | \
 *    Data | +-------------------------+ |
 * section | | maximum value (#n)      | | Entry #n
 *         | +-------------------------+ |
 *         | | default value (#n)      | /
 *         | +-------------------------+
 *         \ | ...                     |
 *           +-------------------------+
 * ~~~~
 *
 * The minimum, maximum and default values are stored in the platform's native
 * data format. The ipa_control_info_entry::offset field stores the offset from
 * the beginning of the data section to the info data.
 *
 * Info 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
 */

/**
 * \var ipa_controls_id_map_type
 * \brief Enumerates the different control id map types
 *
 * Each ControlInfoMap and ControlList refers to a control id map that
 * associates the ControlId references to a numerical identifier.
 * During the serialization procedure the raw pointers to the ControlId
 * instances cannot be transported on the wire, hence their numerical id is
 * used to identify them in the serialized data buffer. At deserialization time
 * it is required to associate back to the numerical id the ControlId instance
 * it represents. This enumeration describes which ControlIdMap should be
 * used to perform such operation.
 *
 * \var ipa_controls_id_map_type::IPA_CONTROL_ID_MAP_CONTROLS
 * \brief The numerical control identifier are resolved to a ControlId * using
 * the global controls::controls id map
 * \var ipa_controls_id_map_type::IPA_CONTROL_ID_MAP_PROPERTIES
 * \brief The numerical control identifier are resolved to a ControlId * using
 * the global properties::properties id map
 * \var ipa_controls_id_map_type::IPA_CONTROL_ID_MAP_V4L2
 * \brief ControlId for V4L2 defined controls are created by the video device
 * that enumerates them, and are not available across the IPC boundaries. The
 * deserializer shall create new ControlId instances for them as well as store
 * them in a dedicated ControlIdMap. Only lookup by numerical id can be
 * performed on de-serialized ControlInfoMap that represents V4L2 controls.
 */

/**
 * \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::id_map_type
 * The id map type as defined by the ipa_controls_id_map_type enumeration
 * \var ipa_controls_header::reserved
 * Reserved for future extensions
 */

static_assert(sizeof(ipa_controls_header) == 32,
	      "Invalid ABI size change for struct ipa_control_header");

/**
 * \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::is_array
 * True if the control value stores an array, false otherwise
 * \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).
 * \var ipa_control_value_entry::padding
 * Padding bytes (shall be set to 0)
 */

static_assert(sizeof(ipa_control_value_entry) == 16,
	      "Invalid ABI size change for struct ipa_control_value_entry");

/**
 * \struct ipa_control_info_entry
 * \brief Description of a serialized ControlInfo entry
 * \var ipa_control_info_entry::id
 * The numerical ID of the control
 * \var ipa_control_info_entry::type
 * The type of the control (defined by enum ControlType)
 * \var ipa_control_info_entry::offset
 * The offset in bytes from the beginning of the data section to the control
 * info data (shall be a multiple of 8 bytes)
 * \var ipa_control_info_entry::padding
 * Padding bytes (shall be set to 0)
 */

static_assert(sizeof(ipa_control_info_entry) == 16,
	      "Invalid ABI size change for struct ipa_control_info_entry");