libcamera: libcamera::ControlSerializer Class Reference

libcamera v0.0.1 Supporting cameras in Linux since 2019

Public Types | Public Member Functions | Static Public Member Functions | List of all members
libcamera::ControlSerializer Class Reference

Serializer and deserializer for control-related classes. More...

## Public Types
enum class | 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...

## Detailed Description

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.

## Member Enumeration Documentation

## ◆ Role

enum class libcamera::ControlSerializer::Role
| 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.

Enumerator
Proxy | The control serializer is used by the IPC Proxy classes.
Worker | The control serializer is used by the IPC ProxyWorker classes.

## Constructor & Destructor Documentation

## ◆ ControlSerializer()

libcamera::ControlSerializer::ControlSerializer | ( | Role | role | ) |

Construct a new ControlSerializer.

Parameters

  [in] | role | The role of the IPC component using the serializer

## Member Function Documentation

## ◆ binarySize() [1/2]

size_t libcamera::ControlSerializer::binarySize | ( | const ControlInfoMap & | infoMap | ) |
| static

Retrieve the size in bytes required to serialize a ControlInfoMap.

Parameters

  [in] | infoMap | The control info map

Compute and return the size in bytes required to store the serialized ControlInfoMap.

Returns
  The size in bytes required to store the serialized ControlInfoMap

## ◆ binarySize() [2/2]

size_t libcamera::ControlSerializer::binarySize | ( | const ControlList & | list | ) |
| static

Retrieve the size in bytes required to serialize a ControlList.

Parameters

  [in] | list | The control list

Compute and return the size in bytes required to store the serialized ControlList.

Returns
  The size in bytes required to store the serialized ControlList

## ◆ deserialize() [1/3]

template<typename T >

template< typename T > T libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |

Deserialize an object from a binary buffer.

Parameters

  [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.

## ◆ deserialize() [2/3]

template<>

ControlInfoMap libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |

Deserialize a ControlInfoMap from a binary buffer.

Parameters

  [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.

Returns
  The deserialized ControlInfoMap

Todo:
  Find a way to preserve the control name for debugging purpose.

## ◆ deserialize() [3/3]

template<>

ControlList libcamera::ControlSerializer::deserialize | ( | ByteStreamBuffer & | buffer | ) |

Deserialize a ControlList from a binary buffer.

Parameters

  [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.

Returns
  The deserialized ControlList

## ◆ isCached()

bool libcamera::ControlSerializer::isCached | ( | const ControlInfoMap & | infoMap | ) |

Check if a ControlInfoMap is cached.

Parameters

  [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.

Returns
  True if infoMap is in the cache or false otherwise

## ◆ reset()

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.

## ◆ serialize() [1/2]

int libcamera::ControlSerializer::serialize | ( | const ControlInfoMap & | infoMap,
|  | ByteStreamBuffer & | buffer
| ) |  |

Serialize a ControlInfoMap in a buffer.

Parameters

  [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().

Returns
  0 on success, a negative error code otherwise

Return values

  -ENOSPC | Not enough space is available in the buffer

## ◆ serialize() [2/2]

int libcamera::ControlSerializer::serialize | ( | const ControlList & | list,
|  | ByteStreamBuffer & | buffer
| ) |  |

Serialize a ControlList in a buffer.

Parameters

  [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.

Returns
  0 on success, a negative error code otherwise

Return values

  -ENOENT | The ControlList is related to an unknown ControlInfoMap
  -ENOSPC | Not enough space is available in the buffer

The documentation for this class was generated from the following files:

- include/libcamera/internal/control_serializer.h
- src/libcamera/control_serializer.cpp