[libcamera-devel,v2,13/24] ipa: Define serialized controls
diff mbox series

Message ID 20191108205409.18845-14-laurent.pinchart@ideasonboard.com
State Accepted
Headers show
Series
  • Control serialization and IPA C API
Related show

Commit Message

Laurent Pinchart Nov. 8, 2019, 8:53 p.m. UTC 
From: Jacopo Mondi <jacopo@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@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

Comments

Jacopo Mondi Nov. 15, 2019, 4:38 p.m. UTC | #1 
Hi Laurent,

some spelling, just that...

On Fri, Nov 08, 2019 at 10:53:58PM +0200, Laurent Pinchart wrote:
> From: Jacopo Mondi <jacopo@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@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/ ?

> + * 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@jmondi.org>

Thanks
   j

> 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
>
Laurent Pinchart Nov. 18, 2019, 1:18 a.m. UTC | #2 
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@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@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@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',
Niklas Söderlund Nov. 18, 2019, 5:46 p.m. UTC | #3 
Hi Jacopo,

Thanks for your work.

On 2019-11-08 22:53:58 +0200, Laurent Pinchart wrote:
> From: Jacopo Mondi <jacopo@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@jmondi.org>

Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

> ---
>  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
> + * 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 platform's native format.
> + *
> + * 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,
> + * 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 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
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel@lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

Patch
diff mbox series 

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
+ * 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 platform's native format.
+ *
+ * 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,
+ * 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 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',