[libcamera-devel] [PATCH v2 13/24] ipa: Define serialized controls
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Mon Nov 18 02:18:02 CET 2019
Hi Jacopo,
On Fri, Nov 15, 2019 at 05:38:34PM +0100, Jacopo Mondi wrote:
> On Fri, Nov 08, 2019 at 10:53:58PM +0200, Laurent Pinchart wrote:
> > From: Jacopo Mondi <jacopo at jmondi.org>
> >
> > 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 at jmondi.org>
> > ---
> > include/ipa/ipa_controls.h | 54 ++++++++++
> > include/ipa/meson.build | 1 +
> > src/libcamera/ipa_controls.cpp | 187 +++++++++++++++++++++++++++++++++
> > src/libcamera/meson.build | 1 +
> > 4 files changed, 243 insertions(+)
> > create mode 100644 include/ipa/ipa_controls.h
> > create mode 100644 src/libcamera/ipa_controls.cpp
> >
> > diff --git a/include/ipa/ipa_controls.h b/include/ipa/ipa_controls.h
> > new file mode 100644
> > index 000000000000..de3a017b0179
> > --- /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 a0ce96ba96c3..695a4183a0e8 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 000000000000..bbcc5301cd59
> > --- /dev/null
> > +++ b/src/libcamera/ipa_controls.cpp
> > @@ -0,0 +1,187 @@
> > +/* 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 packed, and
>
> s/packed/packet
>
> > + * 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.
>
> s/control values/value entries/ ?
While I agree that "control values" may be a bit confusing, I don't like
using "value entries" here as we're documenting a single
ipa_control_value_entry. What I meant was really the number of values,
which is always 1 now, but will be useful later for array controls.
> > + * The control values are stored in the platform's native format.
>
> Repeted below
>
> > + *
> > + * 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 controls in the entries array, shall be aligned to a multiple of 8 bytes,
>
> s/the controls in the entries array/the respective control entries/
>
> > + * 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
> > + */
>
> Minor aparts,
> Reviewed-by: Jacopo Mondi <jacopo at jmondi.org>
>
> > diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
> > index afbca76968f9..be0cd53f6f10 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',
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list