|
libcamera
v0.3.1+12-19bbca3c
Supporting cameras in Linux since 2019
|
Serializer and deserializer for control-related classes. More...
Public Types | |
| enum | Role { Proxy, Worker } |
| Define the role of the IPC component using the control serializer. More... | |
Public Member Functions | |
| ControlSerializer (Role role) | |
| Construct a new ControlSerializer. More... | |
| void | reset () |
| Reset the serializer. More... | |
| int | serialize (const ControlInfoMap &infoMap, ByteStreamBuffer &buffer) |
| Serialize a ControlInfoMap in a buffer. More... | |
| int | serialize (const ControlList &list, ByteStreamBuffer &buffer) |
| Serialize a ControlList in a buffer. More... | |
| template<typename T > | |
| T | deserialize (ByteStreamBuffer &buffer) |
| Deserialize an object from a binary buffer. More... | |
| bool | isCached (const ControlInfoMap &infoMap) |
| Check if a ControlInfoMap is cached. More... | |
| template<> | |
| ControlInfoMap | deserialize (ByteStreamBuffer &buffer) |
| Deserialize a ControlInfoMap from a binary buffer. More... | |
| template<> | |
| ControlList | deserialize (ByteStreamBuffer &buffer) |
| Deserialize a ControlList from a binary buffer. More... | |
Static Public Member Functions | |
| static size_t | binarySize (const ControlInfoMap &infoMap) |
| Retrieve the size in bytes required to serialize a ControlInfoMap. More... | |
| static size_t | binarySize (const ControlList &list) |
| Retrieve the size in bytes required to serialize a ControlList. More... | |
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.
|
strong |
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.
| libcamera::ControlSerializer::ControlSerializer | ( | Role | role | ) |
Construct a new ControlSerializer.
| [in] | role | The role of the IPC component using the serializer |
|
static |
Retrieve the size in bytes required to serialize a ControlInfoMap.
| [in] | infoMap | The control info map |
Compute and return the size in bytes required to store the serialized ControlInfoMap.
|
static |
Retrieve the size in bytes required to serialize a ControlList.
| [in] | list | The control list |
Compute and return the size in bytes required to store the serialized ControlList.
| template< typename T > T libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |
Deserialize an object from a binary buffer.
| [in] | buffer | The memory buffer that contains the object |
This function is only valid when specialized for ControlInfoMap or ControlList. Any other typename T is not supported.
| ControlInfoMap libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |
Deserialize a ControlInfoMap from a binary buffer.
| [in] | buffer | The memory buffer that contains the serialized map |
Re-construct a ControlInfoMap from a binary buffer containing data serialized using the serialize() function.
| ControlList libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |
Deserialize a ControlList from a binary buffer.
| [in] | buffer | The memory buffer that contains the serialized list |
Re-construct a ControlList from a binary buffer containing data serialized using the serialize() function.
| bool libcamera::ControlSerializer::isCached | ( | const ControlInfoMap & | infoMap | ) |
Check if a ControlInfoMap is cached.
| [in] | infoMap | The ControlInfoMap to check |
The ControlSerializer caches all ControlInfoMaps that it has (de)serialized. This function checks if infoMap is in the cache.
| void libcamera::ControlSerializer::reset | ( | ) |
Reset the serializer.
Reset the internal state of the serializer. This invalidates all the ControlList and ControlInfoMap that have been previously deserialized.
| int libcamera::ControlSerializer::serialize | ( | const ControlInfoMap & | infoMap, |
| ByteStreamBuffer & | buffer | ||
| ) |
Serialize a ControlInfoMap in a buffer.
| [in] | infoMap | The control info map to serialize |
| [in] | buffer | The memory buffer where to serialize the ControlInfoMap |
Serialize the infoMap into the buffer using the serialization format defined by the IPA context interface in ipa_controls.h.
The serializer stores a reference to the infoMap internally. The caller shall ensure that infoMap stays valid until the serializer is reset().
| -ENOSPC | Not enough space is available in the buffer |
| int libcamera::ControlSerializer::serialize | ( | const ControlList & | list, |
| ByteStreamBuffer & | buffer | ||
| ) |
Serialize a ControlList in a buffer.
| [in] | list | The control list to serialize |
| [in] | buffer | The memory buffer where to serialize the ControlList |
Serialize the list into the buffer using the serialization format defined by the IPA context interface in ipa_controls.h.
| -ENOENT | The ControlList is related to an unknown ControlInfoMap |
| -ENOSPC | Not enough space is available in the buffer |
1.8.13