@@ -15,6 +15,7 @@ libcamera_headers = files([
'message.h',
'pipeline_handler.h',
'process.h',
+ 'serializer.h',
'thread.h',
'utils.h',
'v4l2_controls.h',
new file mode 100644
@@ -0,0 +1,93 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * serializer.h - Data serializer helpers
+ */
+#ifndef __LIBCAMERA_SERIALIZER_H__
+#define __LIBCAMERA_SERIALIZER_H__
+
+#include <cstdint>
+#include <memory>
+#include <utility>
+
+#include <libcamera/data_value.h>
+
+#include "utils.h"
+
+namespace libcamera {
+
+class Serializer
+{
+public:
+ static constexpr unsigned int BLOB_ALIGN_BYTES = 8;
+ static constexpr unsigned int BLOB_ALIGN(size_t s)
+ {
+ return ALIGN(s, BLOB_ALIGN_BYTES);
+ }
+
+ /*
+ * These offset define the serialization format.
+ * Keep the total headers size 8 bytes aligned.
+ */
+ static constexpr unsigned int VALUE_BLOB_TYPE_OFFS = 4;
+ static constexpr uint8_t *VALUE_BLOB_TYPE(uint8_t *b)
+ {
+
+ return b + VALUE_BLOB_TYPE_OFFS;
+ }
+
+ static constexpr unsigned int VALUE_BLOB_SIZE_OFFS = 8;
+ static constexpr uint8_t *VALUE_BLOB_SIZE(uint8_t *b)
+ {
+ return b + VALUE_BLOB_SIZE_OFFS;
+ }
+
+ static constexpr unsigned int VALUE_BLOB_DATA_OFFS = 16;
+ static constexpr uint8_t *VALUE_BLOB_DATA(uint8_t *b)
+ {
+ return b + VALUE_BLOB_DATA_OFFS;
+ }
+
+ static constexpr unsigned int INFO_BLOB_TYPE_OFFS = 4;
+ static constexpr uint8_t *INFO_BLOB_TYPE(uint8_t *b)
+ {
+ return b + INFO_BLOB_TYPE_OFFS;
+ }
+
+ static constexpr unsigned int INFO_BLOB_SIZE_OFFS = 8;
+ static constexpr uint8_t *INFO_BLOB_SIZE(uint8_t *b)
+ {
+ return b + INFO_BLOB_SIZE_OFFS;
+ }
+
+ static constexpr unsigned int INFO_BLOB_DATA_OFFS = 16;
+ static constexpr uint8_t *INFO_BLOB_DATA(uint8_t *b)
+ {
+ return b + INFO_BLOB_DATA_OFFS;
+ }
+
+ using DataValueTuple = std::tuple<unsigned int, DataValue, size_t>;
+ using DataInfoTuple = std::tuple<unsigned int, DataInfo, size_t>;
+
+ static int serialize(unsigned int id, const DataValue &value,
+ uint8_t *buffer);
+ static DataValueTuple deserializeValue(uint8_t *buffer);
+
+ static int serialize(unsigned int id, const DataInfo &info,
+ uint8_t *buffer);
+ static DataInfoTuple deserializeInfo(uint8_t *buffer);
+
+ static unsigned int size(const DataValue &value);
+ static unsigned int size(const DataInfo &value);
+
+private:
+ static unsigned int dumpValue(const DataValue &value, DataType type,
+ uint8_t *b);
+ static DataValue loadValue(DataType type, uint8_t *b);
+ static DataInfo loadInfo(DataType type, uint8_t *b);
+};
+
+} /* namespace libcamera */
+
+#endif /* __LIBCAMERA_SERIALIZER_H__ */
@@ -28,6 +28,7 @@ libcamera_sources = files([
'request.cpp',
'signal.cpp',
'serializable.cpp',
+ 'serializer.cpp',
'stream.cpp',
'thread.cpp',
'timer.cpp',
new file mode 100644
@@ -0,0 +1,420 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2019, Google Inc.
+ *
+ * serializer.h - Data serializer helpers
+ */
+
+#include "serializer.h"
+
+#include <utility>
+
+#include <libcamera/data_value.h>
+
+/**
+ * \file serializer.h
+ * \brief Helper class for serialization of values and information
+ */
+
+namespace libcamera {
+
+/**
+ * \class Serializer
+ * \brief Helper class that provides operations to serialize values and
+ * information to memory buffers
+ *
+ * The Serializer class provides helper methods to serialize to binary format
+ * DataValue and DataInfo associated with a numerical identifier.
+ *
+ * A data is serialized to a memory buffer using the serialize() operation. It
+ * is responsability of the caller to provide a pointer to an opportunely
+ * allocated memory area, with enough space reserved to contain the whole data
+ * blob representation. The memory size required to contain all serialized data
+ * could be esitameted by using the size() operation when iterating on them.
+ */
+
+/**
+ * \var Serializer::BLOB_ALIGN_BYTES
+ * \brief The blob alignement, in bytes
+ */
+
+/**
+ * \fn Serializer::BLOB_ALIGN()
+ * \brief Align a size \a s to BLOB_ALIGN_BYTES
+ * \param[in] s The size to align
+ * \return Size \a s aligned to BLOB_ALIGN_BYTES
+ */
+
+/**
+ * \var Serializer::VALUE_BLOB_TYPE_OFFS
+ * \brief The offset from the blob start where the value type is encoded
+ */
+
+/**
+ * \fn Serializer::VALUE_BLOB_TYPE()
+ * \brief Return the memory location where the value type is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the type information is
+ * encoded
+ */
+
+/**
+ * \var Serializer::VALUE_BLOB_SIZE_OFFS
+ * \brief The offset from the blob start where the value size is encoded
+ */
+
+/**
+ * \fn Serializer::VALUE_BLOB_SIZE()
+ * \brief Return the memory location where the value size is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the size information is
+ * encoded
+ */
+
+/**
+ * \var Serializer::VALUE_BLOB_DATA_OFFS
+ * \brief The offset from the blob start where the value data is encoded
+ */
+
+/**
+ * \fn Serializer::VALUE_BLOB_DATA()
+ * \brief Return the memory location where the value data is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the data information is
+ * encoded
+ */
+
+/**
+ * \var Serializer::INFO_BLOB_TYPE_OFFS
+ * \brief The offset from the blob start where the value type is encoded
+ */
+
+/**
+ * \fn Serializer::INFO_BLOB_TYPE()
+ * \brief Return the memory location where the value type is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the type information is
+ * encoded
+ */
+
+/**
+ * \var Serializer::INFO_BLOB_SIZE_OFFS
+ * \brief The offset from the blob start where the value size is encoded
+ */
+
+/**
+ * \fn Serializer::INFO_BLOB_SIZE()
+ * \brief Return the memory location where the value size is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the size information is
+ * encoded
+ */
+
+/**
+ * \var Serializer::INFO_BLOB_DATA_OFFS
+ * \brief The offset from the blob start where the value data is encoded
+ */
+
+/**
+ * \fn Serializer::INFO_BLOB_DATA()
+ * \brief Return the memory location where the value data is encoded in buffer
+ * \a b
+ * \param[in] b The memory buffer containing a serialized value
+ * \return The memory location in buffer \b where the data information is
+ * encoded
+ */
+
+/**
+ * \typedef Serializer::DataValueTuple
+ * \brief A tuple that contains a numeric id, a DataValue and a size
+ *
+ * DataTupleValue is used to return the content of a DataValue de-serialization
+ * operation.
+ */
+
+/**
+ * \typedef Serializer::DataInfoTuple
+ * \brief A tuple that contains a numeric id, a DataInfo and a size
+ *
+ * DataTupleInfo is used to return the content of a DataInfo de-serialization
+ * operation.
+ */
+
+/**
+ * \var Serializer::BLOB_ALIGN_BYTES
+ * \brief Memory alignement of the serialized data in bytes
+ */
+
+/**
+ * \brief Serialize a data value into a memory buffer
+ * \param[in] id The identifier associated with the DataValue
+ * \param[in] value The DataValue to serialize
+ * \param[in] buffer The memory area where to serialize the data blob
+ *
+ * A data value is serialized to the following binary sections:
+ * - id: the identifier provided to the operation
+ * - type: the DataType of the DataValue provided to the operation
+ * - size: the size in bytes of the data contained in the DataValue provided
+ * the operation
+ * - data: the data contained in the DataValue provided to the operation
+ * - padding (optional): padding bytes to guarantee alignment to 64-bits
+ * boundary
+ *
+ * The data value is serialized to the following binary format:
+ *
+ * Bytes
+ * Offset: 0 4 8 16 [16 + size]
+ * +----+----+--------+----- ... -----+--- ... ----+
+ * Entry: | id |type| size | data | padding |
+ * +----+----+--------+----- ... ------+--- ... ---+
+ *
+ * \----- HEADER ----\---- DATA ----\--- PADDING ---\
+ *
+ * The operation returns the total number of data written into \a buffer,
+ * which is guaranteed to be aligned to Serializer::BLOB_ALIGN_BYTES boundary.
+ *
+ * The memory buffer pointer \a b is not advanced during serialization, and is
+ * responsibility of the caller to advance it using the returned size to the
+ * next memory location where to serialize data.
+ *
+ * \return The number of bytes written in \a buffer, or a negative error code
+ * in case of errors
+ */
+int Serializer::serialize(unsigned int id, const DataValue &value,
+ uint8_t *buffer)
+{
+ if (!buffer)
+ return -ENOMEM;
+
+ DataType type = value.type();
+ uint8_t *b = buffer;
+
+ *reinterpret_cast<int32_t *>(b) = id;
+ *reinterpret_cast<int32_t *>(VALUE_BLOB_TYPE(b)) = type;
+ *reinterpret_cast<int64_t *>(VALUE_BLOB_SIZE(b)) = BLOB_ALIGN(value.size());
+
+ dumpValue(value, type, VALUE_BLOB_DATA(b));
+
+ return Serializer::size(value);
+}
+
+/**
+ * \brief De-serialize a memory buffer to a tuple containing a DataValue
+ * \param[in] buffer The buffer containing data to de-serialize
+ *
+ * De-serialize a data value and its associated id from the memory buffer
+ * \a b. The de-serialized data are expected to be have been serialized using
+ * the serialize(unsigned int id, const DataValue &value, uint8_t *buffer)
+ * operation, which dumps data to the memory in the format known to this
+ * operation.
+ *
+ * The de-serialized data are returned in a tuple which contains:
+ * - id: the id associated with the de-serialized DataValue
+ * - value: the de-serialized DataValue
+ * - size: the size (in bytes) occupied by the serialized data in the memory
+ * buffer
+ *
+ * The memory buffer pointer \a b is not advanced during de-serialization, and
+ * it is responsibility of the caller to advance it using the returned size to
+ * the next memory location containing data to de-serialize.
+ *
+ * \return A tuple containing the id associated with the de-serialized data, the
+ * data value itself and the size of the size of the de-serialized memory area
+ */
+Serializer::DataValueTuple Serializer::deserializeValue(uint8_t *buffer)
+{
+ if (!buffer)
+ return {};
+
+ uint8_t *b = buffer;
+ unsigned int id = *reinterpret_cast<unsigned int *>(b);
+ DataType type = *reinterpret_cast<DataType *>(VALUE_BLOB_TYPE(b));
+ size_t size = *reinterpret_cast<size_t *>(VALUE_BLOB_SIZE(b));
+
+ b = VALUE_BLOB_DATA(b);
+ return std::make_tuple<unsigned int, DataValue, size_t>(
+ std::forward<unsigned int>(id), loadValue(type, b),
+ std::forward<size_t>(size + VALUE_BLOB_DATA_OFFS));
+}
+
+/**
+ * \brief Serialize a data info into a memory buffer
+ * \param[in] id The identifier associated with the DataValue
+ * \param[in] info The DataInfo to serialize
+ * \param[in] buffer The memory area where to serialize the data blob
+ *
+ * A data info is serialized to the following binary sections:
+ * - id: the identifier provided to the operation
+ * - type: the DataType of the data this info refers to
+ * - size: the size in bytes of the data contained in the DataInfo provided
+ * to the operation
+ * - data: the data contained in the DataInfo provided to the operation:
+ * - min (DataValue of type 'type')
+ * - max (DataValue of type 'type')
+ *
+ * The data value is serialized to the following binary format:
+ *
+ * Bytes
+ * Offset: 0 4 8 16 [16 + size]
+ * +----+----+--------+- ... -+- ... -+
+ * Entry: | id |type| size | min | max |
+ * +----+----+--------+- ... -+- ... -+
+ *
+ * \----- HEADER -----\---- DATA ----\
+ *
+ * The operation returns the total number of data written into \a buffer,
+ * which is guaranteed to be aligned to Serializer::BLOB_ALIGN_BYTES boundary.
+ *
+ * \return The number of bytes written in \a buffer, or a negative error code
+ * in case of errors
+ */
+int Serializer::serialize(unsigned int id, const DataInfo &info,
+ uint8_t *buffer)
+{
+ if (!buffer)
+ return -ENOMEM;
+
+ DataType type = info.min().type();
+ uint8_t *b = buffer;
+
+ *reinterpret_cast<int32_t *>(b) = id;
+ *reinterpret_cast<int32_t *>(INFO_BLOB_TYPE(b)) = type;
+ *reinterpret_cast<int64_t *>(INFO_BLOB_SIZE(b)) = BLOB_ALIGN(DataSize[type]) +
+ BLOB_ALIGN(DataSize[type]);
+
+ b = INFO_BLOB_DATA(b);
+ b += dumpValue(info.min(), type, b);
+ b += dumpValue(info.max(), type, b);
+
+ return Serializer::size(info);
+}
+
+/**
+ * \brief De-serialize a memory buffer to a tuple containing a DataInfo
+ * \param[in] buffer The buffer containing data to de-serialize
+ *
+ * De-serialize a data value and its associated id from the memory buffer
+ * \a b. The de-serialized data are expected to be have been serialized using
+ * the serialize(unsigned int id, const DataInfo &info, uint8_t *buffer)
+ * operation, which dumps data to the memory in the format known to this
+ * operation.
+ *
+ * The de-serialized data are returned in a tuple which contains:
+ * - id: the id associated with the de-serialized DataValue
+ * - info: the de-serialized DataInfo
+ * - size: the size (in bytes) occupied by the serialized data in the memory
+ * buffer
+ *
+ * The memory buffer pointer \a b is not advanced during de-serialization, and
+ * it is responsibility of the caller to advance it using the returned size to
+ * the next memory location containing data to de-serialize.
+ *
+ * \return A tuple containing the id associated with the de-serialized data, the
+ * data value itself and the size of the size of the de-serialized memory area
+ */
+Serializer::DataInfoTuple Serializer::deserializeInfo(uint8_t *buffer)
+{
+ if (!buffer)
+ return {};
+
+ uint8_t *b = buffer;
+ unsigned int id = *reinterpret_cast<unsigned int *>(b);
+ DataType type = *reinterpret_cast<DataType *>((INFO_BLOB_TYPE(b)));
+ size_t size = *reinterpret_cast<size_t *>(INFO_BLOB_SIZE(b));
+
+ b = INFO_BLOB_DATA(b);
+ return std::make_tuple<unsigned int, DataInfo, size_t>(
+ std::forward<unsigned int>(id), loadInfo(type, b),
+ std::forward<size_t>(size + INFO_BLOB_DATA_OFFS));
+}
+
+/**
+ * \brief Calculate the size of the data value once serialized to binary form
+ *
+ * Calculate the data value size in bytes comprising header, data and padding
+ * bytes to guarantee alignement to 64 bits boundary.
+ *
+ * The returned size is the actual byte size occupied by the data blob once
+ * serialized to a memory buffer.
+ *
+ * \return The blob size in bytes, aligned to Serializer::BLOB_ALIGN_BYTES
+ * boundary
+ */
+unsigned int Serializer::size(const DataValue &value)
+{
+ return VALUE_BLOB_DATA_OFFS + BLOB_ALIGN(value.size());
+}
+
+/**
+ * \brief Calculate the size of the data info once serialized to binary form
+ *
+ * Calculate the data info size in bytes comprising header, data and padding
+ * bytes to guarantee alignement to 64 bits boundary.
+ *
+ * The returned size is the actual byte size occupied by the data blob once
+ * serialized to a memory buffer.
+ *
+ * \return The blob size in bytes, aligned to Serializer::BLOB_ALIGN_BYTES
+ * boundary
+ */
+unsigned int Serializer::size(const DataInfo &info)
+{
+ /*
+ * Header is aligned as well as the transported data
+ *
+ * \todo If any non-DataValue field is added to DataInfo, the
+ * total size of the serialized package should be aligned with the
+ * ALIGN() macro.
+ */
+ DataType type = info.min().type();
+ return INFO_BLOB_DATA_OFFS + BLOB_ALIGN(DataSize[type]) +
+ BLOB_ALIGN(DataSize[type]);
+}
+
+unsigned int Serializer::dumpValue(const DataValue &value, DataType type,
+ uint8_t *b)
+{
+ switch (type) {
+ case DataTypeBool:
+ *reinterpret_cast<bool *>(b) = value.getBool();
+ break;
+ case DataTypeInteger:
+ *reinterpret_cast<int32_t *>(b) = value.getInt();
+ break;
+ case DataTypeInteger64:
+ *reinterpret_cast<int64_t *>(b) = value.getInt64();
+ break;
+ default:
+ *b = 0;
+ break;
+ }
+
+ return DataSize[type];
+}
+
+DataValue Serializer::loadValue(DataType type, uint8_t *b)
+{
+ switch (type) {
+ case DataTypeBool:
+ return DataValue(*reinterpret_cast<bool *>(b));
+ case DataTypeInteger:
+ return DataValue(*reinterpret_cast<int *>(b));
+ case DataTypeInteger64:
+ return DataValue(*reinterpret_cast<int64_t *>(b));
+ default:
+ return DataValue();
+ }
+}
+
+DataInfo Serializer::loadInfo(DataType type, uint8_t *b)
+{
+ return DataInfo(loadValue(type, b),
+ loadValue(type, b + BLOB_ALIGN(DataSize[type])));
+}
+
+} /* namespace libcamera */
Define and implement a Serializer class which provides static operations used to serialize and de-serialize DataValue and DataInfo instances to and from a memory buffers. The helpers implementation define the binary serialization format to which data are dumped to and restored from. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> --- src/libcamera/include/meson.build | 1 + src/libcamera/include/serializer.h | 93 +++++++ src/libcamera/meson.build | 1 + src/libcamera/serializer.cpp | 420 +++++++++++++++++++++++++++++ 4 files changed, 515 insertions(+) create mode 100644 src/libcamera/include/serializer.h create mode 100644 src/libcamera/serializer.cpp