diff options
| -rw-r--r-- | src/libcamera/control_serializer.cpp | 510 | ||||
| -rw-r--r-- | src/libcamera/include/control_serializer.h | 52 | ||||
| -rw-r--r-- | src/libcamera/include/meson.build | 1 | ||||
| -rw-r--r-- | src/libcamera/meson.build | 1 |
4 files changed, 564 insertions, 0 deletions
diff --git a/src/libcamera/control_serializer.cpp b/src/libcamera/control_serializer.cpp new file mode 100644 index 00000000..b787655e --- /dev/null +++ b/src/libcamera/control_serializer.cpp @@ -0,0 +1,510 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2019, Google Inc. + * + * control_serializer.cpp - Control (de)serializer + */ + +#include "control_serializer.h" + +#include <algorithm> +#include <memory> +#include <vector> + +#include <ipa/ipa_controls.h> +#include <libcamera/control_ids.h> +#include <libcamera/controls.h> + +#include "byte_stream_buffer.h" +#include "log.h" + +/** + * \file control_serializer.h + * \brief Serialization and deserialization helpers for controls + */ + +namespace libcamera { + +LOG_DEFINE_CATEGORY(Serializer) + +namespace { + +static constexpr size_t ControlValueSize[] = { + [ControlTypeNone] = 1, + [ControlTypeBool] = sizeof(bool), + [ControlTypeInteger32] = sizeof(int32_t), + [ControlTypeInteger64] = sizeof(int64_t), +}; + +} /* namespace */ + +/** + * \class ControlSerializer + * \brief Serializer and deserializer for control-related classes + * + * The control serializer is a helper to serialize and deserialize + * ControlInfoMap and ControlValue instances for the purpose of communication + * with IPA modules. + * + * Neither the ControlInfoMap nor the ControlList are self-contained data + * container. ControlInfoMap references an external ControlId in each of its + * entries, and ControlList references a ControlInfoMap for the purpose of + * validation. Serializing and deserializing those objects thus requires a + * context that maintains the associations between them. The control serializer + * fulfils this task. + * + * ControlInfoMap instances can be serialized on their own, but require + * ControlId instances to be provided at deserialization time. The serializer + * recreates those ControlId instances and stores them in an internal cache, + * from which the ControlInfoMap is populated. + * + * ControlList instances need to be associated with a ControlInfoMap when + * deserialized. To make this possible, the control lists are serialized with a + * handle to their ControlInfoMap, and the map is looked up from the handle at + * deserialization time. To make this possible, the serializer assigns a + * numerical handle to ControlInfoMap instances when they are serialized, and + * stores the mapping between handle and ControlInfoMap both when serializing + * (for the pipeline handler side) and deserializing (for the IPA side) them. + * This mapping is used when serializing a ControlList to include the + * corresponding ControlInfoMap handle in the binary data, and when + * deserializing to retrieve the corresponding ControlInfoMap. + * + * In order to perform those tasks, the serializer keeps an internal state that + * needs to be properly populated. This mechanism requires the ControlInfoMap + * corresponding to a ControlList to have been serialized or deserialized + * before the ControlList is serialized or deserialized. Failure to comply with + * that constraint results in serialization or deserialization failure of the + * ControlList. + * + * The serializer can be reset() to clear its internal state. This may be + * performed when reconfiguring an IPA to avoid constant growth of the internal + * state, especially if the contents of the ControlInfoMap instances change at + * that time. A reset of the serializer invalidates all ControlList and + * ControlInfoMap that have been previously deserialized. The caller shall thus + * proceed with care to avoid stale references. + */ + +/** + * \brief Reset the serializer + * + * Reset the internal state of the serializer. This invalidates all the + * ControlList and ControlInfoMap that have been previously deserialized. + */ +void ControlSerializer::reset() +{ + serial_ = 0; + + infoMapHandles_.clear(); + infoMaps_.clear(); + controlIds_.clear(); +} + +size_t ControlSerializer::binarySize(const ControlValue &value) +{ + return ControlValueSize[value.type()]; +} + +size_t ControlSerializer::binarySize(const ControlRange &range) +{ + return binarySize(range.min()) + binarySize(range.max()); +} + +/** + * \brief Retrieve the size in bytes required to serialize a ControlInfoMap + * \param[in] info The control info map + * + * Compute and return the size in bytes required to store the serialized + * ControlInfoMap. + * + * \return The size in bytes required to store the serialized ControlInfoMap + */ +size_t ControlSerializer::binarySize(const ControlInfoMap &info) +{ + size_t size = sizeof(struct ipa_controls_header) + + info.size() * sizeof(struct ipa_control_range_entry); + + for (const auto &ctrl : info) + size += binarySize(ctrl.second); + + return size; +} + +/** + * \brief Retrieve the size in bytes required to serialize a ControlList + * \param[in] list The control list + * + * Compute and return the size in bytes required to store the serialized + * ControlList. + * + * \return The size in bytes required to store the serialized ControlList + */ +size_t ControlSerializer::binarySize(const ControlList &list) +{ + size_t size = sizeof(struct ipa_controls_header) + + list.size() * sizeof(struct ipa_control_value_entry); + + for (const auto &ctrl : list) + size += binarySize(ctrl.second); + + return size; +} + +void ControlSerializer::store(const ControlValue &value, + ByteStreamBuffer &buffer) +{ + switch (value.type()) { + case ControlTypeBool: { + bool data = value.get<bool>(); + buffer.write(&data); + break; + } + + case ControlTypeInteger32: { + int32_t data = value.get<int32_t>(); + buffer.write(&data); + break; + } + + case ControlTypeInteger64: { + uint64_t data = value.get<int64_t>(); + buffer.write(&data); + break; + } + + default: + break; + } +} + +void ControlSerializer::store(const ControlRange &range, + ByteStreamBuffer &buffer) +{ + store(range.min(), buffer); + store(range.max(), buffer); +} + +/** + * \brief Serialize a ControlInfoMap in a buffer + * \param[in] info The control info map to serialize + * \param[in] buffer The memory buffer where to serialize the ControlInfoMap + * + * Serialize the \a info map into the \a buffer using the serialization format + * defined by the IPA context interface in ipa_controls.h. + * + * The serializer stores a reference to the \a info internally. The caller + * shall ensure that \a info stays valid until the serializer is reset(). + * + * \return 0 on success, a negative error code otherwise + * \retval -ENOSPC Not enough space is available in the buffer + */ +int ControlSerializer::serialize(const ControlInfoMap &info, + ByteStreamBuffer &buffer) +{ + /* Compute entries and data required sizes. */ + size_t entriesSize = info.size() * sizeof(struct ipa_control_range_entry); + size_t valuesSize = 0; + for (const auto &ctrl : info) + valuesSize += binarySize(ctrl.second); + + /* Prepare the packet header, assign a handle to the ControlInfoMap. */ + struct ipa_controls_header hdr; + hdr.version = IPA_CONTROLS_FORMAT_VERSION; + hdr.handle = ++serial_; + hdr.entries = info.size(); + hdr.size = sizeof(hdr) + entriesSize + valuesSize; + hdr.data_offset = sizeof(hdr) + entriesSize; + + buffer.write(&hdr); + + /* + * Serialize all entries. + * \todo Serialize the control name too + */ + ByteStreamBuffer entries = buffer.carveOut(entriesSize); + ByteStreamBuffer values = buffer.carveOut(valuesSize); + + for (const auto &ctrl : info) { + const ControlId *id = ctrl.first; + const ControlRange &range = ctrl.second; + + struct ipa_control_range_entry entry; + entry.id = id->id(); + entry.type = id->type(); + entry.offset = values.offset(); + entries.write(&entry); + + store(range, values); + } + + if (buffer.overflow()) + return -ENOSPC; + + /* + * Store the map to handle association, to be used to serialize and + * deserialize control lists. + */ + infoMapHandles_[&info] = hdr.handle; + + return 0; +} + +/** + * \brief Serialize a ControlList in a buffer + * \param[in] list The control list to serialize + * \param[in] buffer The memory buffer where to serialize the ControlList + * + * Serialize the \a list into the \a buffer using the serialization format + * defined by the IPA context interface in ipa_controls.h. + * + * \return 0 on success, a negative error code otherwise + * \retval -ENOENT The ControlList is related to an unknown ControlInfoMap + * \retval -ENOSPC Not enough space is available in the buffer + */ +int ControlSerializer::serialize(const ControlList &list, + ByteStreamBuffer &buffer) +{ + /* + * Find the ControlInfoMap handle for the ControlList if it has one, or + * use 0 for ControlList without a ControlInfoMap. + */ + unsigned int infoMapHandle; + if (list.infoMap()) { + auto iter = infoMapHandles_.find(list.infoMap()); + if (iter == infoMapHandles_.end()) { + LOG(Serializer, Error) + << "Can't serialize ControlList: unknown ControlInfoMap"; + return -ENOENT; + } + + infoMapHandle = iter->second; + } else { + infoMapHandle = 0; + } + + size_t entriesSize = list.size() * sizeof(struct ipa_control_value_entry); + size_t valuesSize = 0; + for (const auto &ctrl : list) + valuesSize += binarySize(ctrl.second); + + /* Prepare the packet header. */ + struct ipa_controls_header hdr; + hdr.version = IPA_CONTROLS_FORMAT_VERSION; + hdr.handle = infoMapHandle; + hdr.entries = list.size(); + hdr.size = sizeof(hdr) + entriesSize + valuesSize; + hdr.data_offset = sizeof(hdr) + entriesSize; + + buffer.write(&hdr); + + ByteStreamBuffer entries = buffer.carveOut(entriesSize); + ByteStreamBuffer values = buffer.carveOut(valuesSize); + + /* Serialize all entries. */ + for (const auto &ctrl : list) { + unsigned int id = ctrl.first; + const ControlValue &value = ctrl.second; + + struct ipa_control_value_entry entry; + entry.id = id; + entry.count = 1; + entry.type = value.type(); + entry.offset = values.offset(); + entries.write(&entry); + + store(value, values); + } + + if (buffer.overflow()) + return -ENOSPC; + + return 0; +} + +template<> +ControlValue ControlSerializer::load<ControlValue>(ControlType type, + ByteStreamBuffer &b) +{ + switch (type) { + case ControlTypeBool: { + bool value; + b.read(&value); + return ControlValue(value); + } + + case ControlTypeInteger32: { + int32_t value; + b.read(&value); + return ControlValue(value); + } + + case ControlTypeInteger64: { + int64_t value; + b.read(&value); + return ControlValue(value); + } + + default: + return ControlValue(); + } +} + +template<> +ControlRange ControlSerializer::load<ControlRange>(ControlType type, + ByteStreamBuffer &b) +{ + ControlValue min = load<ControlValue>(type, b); + ControlValue max = load<ControlValue>(type, b); + + return ControlRange(min, max); +} + +/** + * \fn template<typename T> T ControlSerializer::deserialize(ByteStreamBuffer &buffer) + * \brief Deserialize an object from a binary buffer + * \param[in] buffer The memory buffer that contains the object + * + * This method is only valid when specialized for ControlInfoMap or + * ControlList. Any other typename \a T is not supported. + */ + +/** + * \brief Deserialize a ControlInfoMap from a binary buffer + * \param[in] buffer The memory buffer that contains the serialized map + * + * Re-construct a ControlInfoMap from a binary \a buffer containing data + * serialized using the serialize() method. + * + * \return The deserialized ControlInfoMap + */ +template<> +ControlInfoMap ControlSerializer::deserialize<ControlInfoMap>(ByteStreamBuffer &buffer) +{ + struct ipa_controls_header hdr; + buffer.read(&hdr); + + if (hdr.version != IPA_CONTROLS_FORMAT_VERSION) { + LOG(Serializer, Error) + << "Unsupported controls format version " + << hdr.version; + return {}; + } + + ByteStreamBuffer entries = buffer.carveOut(hdr.data_offset - sizeof(hdr)); + ByteStreamBuffer values = buffer.carveOut(hdr.size - hdr.data_offset); + + if (buffer.overflow()) { + LOG(Serializer, Error) << "Serialized packet too small"; + return {}; + } + + ControlInfoMap::Map ctrls; + + for (unsigned int i = 0; i < hdr.entries; ++i) { + struct ipa_control_range_entry entry; + entries.read(&entry); + + /* Create and cache the individual ControlId. */ + ControlType type = static_cast<ControlType>(entry.type); + /** + * \todo Find a way to preserve the control name for debugging + * purpose. + */ + controlIds_.emplace_back(utils::make_unique<ControlId>(entry.id, "", type)); + + if (entry.offset != values.offset()) { + LOG(Serializer, Error) + << "Bad data, entry offset mismatch (entry " + << i << ")"; + return {}; + } + + /* Create and store the ControlRange. */ + ctrls.emplace(controlIds_.back().get(), + load<ControlRange>(type, values)); + } + + /* + * Create the ControlInfoMap in the cache, and store the map to handle + * association. + */ + ControlInfoMap &map = infoMaps_[hdr.handle] = std::move(ctrls); + infoMapHandles_[&map] = hdr.handle; + + return map; +} + +/** + * \brief Deserialize a ControlList from a binary buffer + * \param[in] buffer The memory buffer that contains the serialized list + * + * Re-construct a ControlList from a binary \a buffer containing data + * serialized using the serialize() method. + * + * \return The deserialized ControlList + */ +template<> +ControlList ControlSerializer::deserialize<ControlList>(ByteStreamBuffer &buffer) +{ + struct ipa_controls_header hdr; + buffer.read(&hdr); + + if (hdr.version != IPA_CONTROLS_FORMAT_VERSION) { + LOG(Serializer, Error) + << "Unsupported controls format version " + << hdr.version; + return {}; + } + + ByteStreamBuffer entries = buffer.carveOut(hdr.data_offset - sizeof(hdr)); + ByteStreamBuffer values = buffer.carveOut(hdr.size - hdr.data_offset); + + if (buffer.overflow()) { + LOG(Serializer, Error) << "Serialized packet too small"; + return {}; + } + + /* + * Retrieve the ControlInfoMap associated with the ControlList based on + * its ID. The mapping between infoMap and ID is set up when serializing + * or deserializing ControlInfoMap. If no mapping is found (which is + * currently the case for ControlList related to libcamera controls), + * use the global control::control idmap. + */ + const ControlInfoMap *infoMap; + if (hdr.handle) { + auto iter = std::find_if(infoMapHandles_.begin(), infoMapHandles_.end(), + [&](decltype(infoMapHandles_)::value_type &entry) { + return entry.second == hdr.handle; + }); + if (iter == infoMapHandles_.end()) { + LOG(Serializer, Error) + << "Can't deserialize ControlList: unknown ControlInfoMap"; + return {}; + } + + infoMap = iter->first; + } else { + infoMap = nullptr; + } + + ControlList ctrls(infoMap ? infoMap->idmap() : controls::controls); + + for (unsigned int i = 0; i < hdr.entries; ++i) { + struct ipa_control_value_entry entry; + entries.read(&entry); + + if (entry.offset != values.offset()) { + LOG(Serializer, Error) + << "Bad data, entry offset mismatch (entry " + << i << ")"; + return {}; + } + + ControlType type = static_cast<ControlType>(entry.type); + ctrls.set(entry.id, load<ControlValue>(type, values)); + } + + return ctrls; +} + +} /* namespace libcamera */ diff --git a/src/libcamera/include/control_serializer.h b/src/libcamera/include/control_serializer.h new file mode 100644 index 00000000..bb3cb8e7 --- /dev/null +++ b/src/libcamera/include/control_serializer.h @@ -0,0 +1,52 @@ +/* SPDX-License-Identifier: LGPL-2.1-or-later */ +/* + * Copyright (C) 2019, Google Inc. + * + * control_serializer.h - Control (de)serializer + */ +#ifndef __LIBCAMERA_CONTROL_SERIALIZER_H__ +#define __LIBCAMERA_CONTROL_SERIALIZER_H__ + +#include <map> +#include <memory> +#include <vector> + +#include <libcamera/controls.h> + +namespace libcamera { + +class ByteStreamBuffer; + +class ControlSerializer +{ +public: + void reset(); + + static size_t binarySize(const ControlInfoMap &info); + static size_t binarySize(const ControlList &list); + + int serialize(const ControlInfoMap &info, ByteStreamBuffer &buffer); + int serialize(const ControlList &list, ByteStreamBuffer &buffer); + + template<typename T> + T deserialize(ByteStreamBuffer &buffer); + +private: + static size_t binarySize(const ControlValue &value); + static size_t binarySize(const ControlRange &range); + + static void store(const ControlValue &value, ByteStreamBuffer &buffer); + static void store(const ControlRange &range, ByteStreamBuffer &buffer); + + template<typename T> + T load(ControlType type, ByteStreamBuffer &b); + + unsigned int serial_; + std::vector<std::unique_ptr<ControlId>> controlIds_; + std::map<unsigned int, ControlInfoMap> infoMaps_; + std::map<const ControlInfoMap *, unsigned int> infoMapHandles_; +}; + +} /* namespace libcamera */ + +#endif /* __LIBCAMERA_CONTROL_SERIALIZER_H__ */ diff --git a/src/libcamera/include/meson.build b/src/libcamera/include/meson.build index 1ff01986..697294f4 100644 --- a/src/libcamera/include/meson.build +++ b/src/libcamera/include/meson.build @@ -2,6 +2,7 @@ libcamera_headers = files([ 'byte_stream_buffer.h', 'camera_controls.h', 'camera_sensor.h', + 'control_serializer.h', 'control_validator.h', 'device_enumerator.h', 'device_enumerator_sysfs.h', diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build index dab2d8ad..59cf5825 100644 --- a/src/libcamera/meson.build +++ b/src/libcamera/meson.build @@ -7,6 +7,7 @@ libcamera_sources = files([ 'camera_manager.cpp', 'camera_sensor.cpp', 'controls.cpp', + 'control_serializer.cpp', 'control_validator.cpp', 'device_enumerator.cpp', 'device_enumerator_sysfs.cpp', |