libcamera/pinchartl/libcamera.git - Laurent Pinchart's clone of libcamera

diff options

Diffstat (limited to 'src')

-rw-r--r--

2 files changed, 13 insertions, 2 deletions

/* SPDX-License-Identifier: LGPL-2.1-or-later */ /* * Copyright (C) 2019, Google Inc. * * control_serializer.cpp - Control (de)serializer */ #include "libcamera/internal/control_serializer.h" #include <algorithm> #include <memory> #include <vector> #include <libcamera/base/log.h> #include <libcamera/base/span.h> #include <libcamera/control_ids.h> #include <libcamera/controls.h> #include <libcamera/property_ids.h> #include <libcamera/ipa/ipa_controls.h> #include "libcamera/internal/byte_stream_buffer.h" /** * \file control_serializer.h * \brief Serialization and deserialization helpers for controls */ namespace libcamera { LOG_DEFINE_CATEGORY(Serializer) /** * \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. * * As independent ControlSerializer instances are used on both sides of the IPC * boundary, and the two instances operate without a shared point of control, * there is a potential risk of collision of the numerical handles assigned to * each serialized ControlInfoMap. For this reason the control serializer is * initialized with a seed and the handle is incremented by 2, so that instances * initialized with a different seed operate on a separate numerical space, * avoiding any collision risk. * * 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. */ /** * \enum ControlSerializer::Role * \brief Define the role of the IPC component using the control serializer * * The role of the component that creates the serializer is used to initialize * the handles numerical space. * * \var ControlSerializer::Role::Proxy * \brief The control serializer is used by the IPC Proxy classes * * \var ControlSerializer::Role::Worker * \brief The control serializer is used by the IPC ProxyWorker classes */ /** * \brief Construct a new ControlSerializer * \param[in] role The role of the IPC component using the serializer */ ControlSerializer::ControlSerializer(Role role) { /* * Initialize the handle numerical space using the role of the * component that created the instance. * * Instances initialized for a different role will use a different * numerical handle space, avoiding any collision risk when, in example, * two instances of the ControlSerializer class are used at the IPC * boundaries. * * Start counting handles from '1' as '0' is a special value used as * place holder when serializing lists that do not have a ControlInfoMap * associated (in example list of libcamera controls::controls). * * \todo This is a temporary hack and should probably be better * engineered, but for the time being it avoids collisions on the handle * value when using IPC. */ serialSeed_ = role == Role::Proxy ? 1 : 2; serial_ = serialSeed_; } /** * \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_ = serialSeed_; infoMapHandles_.clear(); infoMaps_.clear(); controlIds_.clear(); controlIdMaps_.clear(); } size_t ControlSerializer::binarySize(const ControlValue &value) { return value.data().size_bytes(); } size_t ControlSerializer::binarySize(const ControlInfo &info) { return binarySize(info.min()) + binarySize(info.max()) + binarySize(info.def()); } /** * \brief Retrieve the size in bytes required to serialize a ControlInfoMap * \param[in] infoMap 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 &infoMap) { size_t size = sizeof(struct ipa_controls_header) + infoMap.size() * sizeof(struct ipa_control_info_entry); for (const auto &ctrl : infoMap) 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) { buffer.write(value.data()); } void ControlSerializer::store(const ControlInfo &info, ByteStreamBuffer &buffer) { store(info.min(), buffer); store(info.max(), buffer); store(info.def(), buffer); } /** * \brief Serialize a ControlInfoMap in a buffer * \param[in] infoMap The control info map to serialize * \param[in] buffer The memory buffer where to serialize the ControlInfoMap * * Serialize the \a infoMap 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 infoMap internally. The caller * shall ensure that \a infoMap 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 &infoMap, ByteStreamBuffer &buffer) { if (isCached(infoMap)) { LOG(Serializer, Debug) << "Skipping already serialized ControlInfoMap"; return 0; } /* Compute entries and data required sizes. */ size_t entriesSize = infoMap.size() * sizeof(struct ipa_control_info_entry); size_t valuesSize = 0; for (const auto &ctrl : infoMap) valuesSize += binarySize(ctrl.second); const ControlIdMap *idmap = &infoMap.idmap(); enum ipa_controls_id_map_type idMapType; if (idmap == &controls::controls) idMapType = IPA_CONTROL_ID_MAP_CONTROLS; else if (idmap == &properties::properties) idMapType = IPA_CONTROL_ID_MAP_PROPERTIES; else idMapType = IPA_CONTROL_ID_MAP_V4L2; /* Prepare the packet header. */ struct ipa_controls_header hdr; hdr.version = IPA_CONTROLS_FORMAT_VERSION; hdr.handle = serial_; hdr.entries = infoMap.size(); hdr.size = sizeof(hdr) + entriesSize + valuesSize; hdr.data_offset = sizeof(hdr) + entriesSize; hdr.id_map_type = idMapType; buffer.write(&hdr); /* * Increment the handle for the ControlInfoMap by 2 to keep the handles * numerical space partitioned between instances initialized for a * different role. * * \sa ControlSerializer::Role */ serial_ += 2; /* * Serialize all entries. * \todo Serialize the control name too */ ByteStreamBuffer entries = buffer.carveOut(entriesSize); ByteStreamBuffer values = buffer.carveOut(valuesSize); for (const auto &ctrl : infoMap) { const ControlId *id = ctrl.first; const ControlInfo &info = ctrl.second; struct ipa_control_info_entry entry; entry.id = id->id(); entry.type = id->type(); entry.offset = values.offset(); entries.write(&entry); store(info, values); } if (buffer.overflow()) return -ENOSPC; /* * Store the map to handle association, to be used to serialize and * deserialize control lists. */ infoMapHandles_[&infoMap] = 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; } const ControlIdMap *idmap = list.idMap(); enum ipa_controls_id_map_type idMapType; if (idmap == &controls::controls) idMapType = IPA_CONTROL_ID_MAP_CONTROLS; else if (idmap == &properties::properties) idMapType = IPA_CONTROL_ID_MAP_PROPERTIES; else idMapType = IPA_CONTROL_ID_MAP_V4L2; 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; hdr.id_map_type = idMapType; 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.type = value.type(); entry.is_array = value.isArray(); entry.count = value.numElements(); entry.offset = values.offset(); entries.write(&entry); store(value, values); } if (buffer.overflow()) return -ENOSPC; return 0; } ControlValue ControlSerializer::loadControlValue(ControlType type, ByteStreamBuffer &buffer, bool isArray, unsigned int count) { ControlValue value; value.reserve(type, isArray, count); buffer.read(value.data()); return value; } ControlInfo ControlSerializer::loadControlInfo(ControlType type, ByteStreamBuffer &b) { if (type == ControlTypeString) type = ControlTypeInteger32; ControlValue min = loadControlValue(type, b); ControlValue max = loadControlValue(type, b); ControlValue def = loadControlValue(type, b); return ControlInfo(min, max, def); } /** * \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 function 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() function. * * \return The deserialized ControlInfoMap */ template<> ControlInfoMap ControlSerializer::deserialize<ControlInfoMap>(ByteStreamBuffer &buffer) { const struct ipa_controls_header *hdr = buffer.read<decltype(*hdr)>(); if (!hdr) { LOG(Serializer, Error) << "Out of data"; return {}; } auto iter = infoMaps_.find(hdr->handle); if (iter != infoMaps_.end()) { LOG(Serializer, Debug) << "Use cached ControlInfoMap"; return iter->second; } if (hdr->version != IPA_CONTROLS_FORMAT_VERSION) { LOG(Serializer, Error) << "Unsupported controls format version " << hdr->version; return {}; } /* * Use the ControlIdMap corresponding to the id map type. If the type * references a globally defined id map (such as controls::controls * or properties::properties), use it. Otherwise, create a local id map * that will be populated with dynamically created ControlId instances * when deserializing individual ControlInfoMap entries. */ const ControlIdMap *idMap = nullptr; ControlIdMap *localIdMap = nullptr; switch (hdr->id_map_type) { case IPA_CONTROL_ID_MAP_CONTROLS: idMap = &controls::controls; break; case IPA_CONTROL_ID_MAP_PROPERTIES: idMap = &properties::properties; break; case IPA_CONTROL_ID_MAP_V4L2: controlIdMaps_.emplace_back(std::make_unique<ControlIdMap>()); localIdMap = controlIdMaps_.back().get(); idMap = localIdMap; break; default: LOG(Serializer, Error) << "Unknown id map type: " << hdr->id_map_type; 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) << "Out of data"; return {}; } ControlInfoMap::Map ctrls; for (unsigned int i = 0; i < hdr->entries; ++i) { const struct ipa_control_info_entry *entry = entries.read<decltype(*entry)>(); if (!entry) { LOG(Serializer, Error) << "Out of data"; return {}; } ControlType type = static_cast<ControlType>(entry->type); /* If we're using a local id map, populate it. */ if (localIdMap) { /** * \todo Find a way to preserve the control name for * debugging purpose. */ controlIds_.emplace_back(std::make_unique<ControlId>(entry->id, "", type)); (*localIdMap)[entry->id] = controlIds_.back().get(); } const ControlId *controlId = idMap->at(entry->id); ASSERT(controlId); if (entry->offset != values.offset()) { LOG(Serializer, Error) << "Bad data, entry offset mismatch (entry " << i << ")"; return {}; } /* Create and store the ControlInfo. */ ctrls.emplace(controlId, loadControlInfo(type, values)); } /* * Create the ControlInfoMap in the cache, and store the map to handle * association. */ infoMaps_[hdr->handle] = ControlInfoMap(std::move(ctrls), *idMap); ControlInfoMap &map = infoMaps_[hdr->handle]; 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() function. * * \return The deserialized ControlList */ template<> ControlList ControlSerializer::deserialize<ControlList>(ByteStreamBuffer &buffer) { const struct ipa_controls_header *hdr = buffer.read<decltype(*hdr)>(); if (!hdr) { LOG(Serializer, Error) << "Out of data"; return {}; } 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) << "Out of data"; return {}; } /* * Retrieve the ControlIdMap associated with the ControlList. * * The idmap is either retrieved from the list's ControlInfoMap when * a valid handle has been initialized at serialization time, or by * using the header's id_map_type field for lists that refer to the * globally defined libcamera controls and properties, for which no * ControlInfoMap is available. */ const ControlIdMap *idMap; 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 {}; } const ControlInfoMap *infoMap = iter->first; idMap = &infoMap->idmap(); } else { switch (hdr->id_map_type) { case IPA_CONTROL_ID_MAP_CONTROLS: idMap = &controls::controls; break; case IPA_CONTROL_ID_MAP_PROPERTIES: idMap = &properties::properties; break; case IPA_CONTROL_ID_MAP_V4L2: default: LOG(Serializer, Fatal) << "A list of V4L2 controls requires an ControlInfoMap"; return {}; } } /* * \todo When available, initialize the list with the ControlInfoMap * so that controls can be validated against their limits. * Currently no validation is performed, so it's fine relying on the * idmap only. */ ControlList ctrls(*idMap); for (unsigned int i = 0; i < hdr->entries; ++i) { const struct ipa_control_value_entry *entry = entries.read<decltype(*entry)>(); if (!entry) { LOG(Serializer, Error) << "Out of data"; return {}; } 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, loadControlValue(type, values, entry->is_array, entry->count)); } return ctrls; } /** * \brief Check if a ControlInfoMap is cached * \param[in] infoMap The ControlInfoMap to check * * The ControlSerializer caches all ControlInfoMaps that it has (de)serialized. * This function checks if \a infoMap is in the cache. * * \return True if \a infoMap is in the cache or false otherwise */ bool ControlSerializer::isCached(const ControlInfoMap &infoMap) { return infoMapHandles_.count(&infoMap); } } /* namespace libcamera */


context:
space:
mode: