libcamera: libcamera::ByteStreamBuffer Class Reference

libcamera v0.0.1 Supporting cameras in Linux since 2019

Public Member Functions | List of all members
libcamera::ByteStreamBuffer Class Reference

Wrap a memory buffer and provide sequential data read and write. More...

## Public Member Functions
| ByteStreamBuffer (const uint8_t *base, size_t size)
| Construct a read ByteStreamBuffer from the memory area base of size. More...
| ByteStreamBuffer (uint8_t *base, size_t size)
| Construct a write ByteStreamBuffer from the memory area base of size. More...
| ByteStreamBuffer (ByteStreamBuffer &&other)
| Construct a ByteStreamBuffer from the contents of other using move semantics. More...
ByteStreamBuffer & | operator= (ByteStreamBuffer &&other)
| Replace the contents of the buffer with those of other using move semantics. More...
const uint8_t * | base () const
| Retrieve a pointer to the start location of the managed memory buffer. More...
uint32_t | offset () const
| Retrieve the offset of the current access location from the base. More...
size_t | size () const
| Retrieve the size of the managed memory buffer. More...
bool | overflow () const
| Check if the buffer has overflown. More...
ByteStreamBuffer | carveOut (size_t size)
| Carve out an area of size bytes into a new ByteStreamBuffer. More...
int | skip (size_t size)
| Skip size bytes from the buffer. More...
template<typename T >
int | read (T *t)
| Read data from the managed memory buffer into t. More...
template<typename T >
int | read (const Span< T > &data)
| Read data from the managed memory buffer into Span data. More...
template<typename T >
const std::remove_reference_t< T > * | read (size_t count=1)
| Read data from the managed memory buffer without performing a copy. More...
template<typename T >
int | write (const T *t)
| Write t to the managed memory buffer. More...
template<typename T >
int | write (const Span< T > &data)
| Write data to the managed memory buffer. More...

## Detailed Description

Wrap a memory buffer and provide sequential data read and write.

The ByteStreamBuffer class wraps a memory buffer and exposes sequential read and write operation with integrated boundary checks. Access beyond the end of the buffer are blocked and logged, allowing error checks to take place at the of of access operations instead of at each access. This simplifies serialization and deserialization of data.

A byte stream buffer is created with a base memory pointer and a size. If the memory pointer is const, the buffer operates in read-only mode, and write operations are denied. Otherwise the buffer operates in write-only mode, and read operations are denied.

Once a buffer is created, data is read or written with read() and write() respectively. Access is strictly sequential, the buffer keeps track of the current access location and advances it automatically. Reading or writing the same location multiple times is thus not possible. Bytes may also be skipped with the skip() function.

The ByteStreamBuffer also supports carving out pieces of memory into other ByteStreamBuffer instances. Like a read or write operation, a carveOut() advances the internal access location, but allows the carved out memory to be accessed at a later time.

All accesses beyond the end of the buffer (read, write, skip or carve out) are blocked. The first of such accesses causes a message to be logged, and the buffer being marked as having overflown. If the buffer has been carved out from a parent buffer, the parent buffer is also marked as having overflown. Any later access on an overflown buffer is blocked. The buffer overflow status can be checked with the overflow() function.

## Constructor & Destructor Documentation

## ◆ ByteStreamBuffer() [1/3]

libcamera::ByteStreamBuffer::ByteStreamBuffer | ( | const uint8_t * | base,
|  | size_t | size
| ) |  |

Construct a read ByteStreamBuffer from the memory area base of size.

Parameters

  [in] | base | The address of the memory area to wrap
  [in] | size | The size of the memory area to wrap

## ◆ ByteStreamBuffer() [2/3]

libcamera::ByteStreamBuffer::ByteStreamBuffer | ( | uint8_t * | base,
|  | size_t | size
| ) |  |

Construct a write ByteStreamBuffer from the memory area base of size.

Parameters

  [in] | base | The address of the memory area to wrap
  [in] | size | The size of the memory area to wrap

## ◆ ByteStreamBuffer() [3/3]

libcamera::ByteStreamBuffer::ByteStreamBuffer | ( | ByteStreamBuffer && | other | ) |

Construct a ByteStreamBuffer from the contents of other using move semantics.

Parameters

  [in] | other | The other buffer

After the move construction the other buffer is invalidated. Any attempt to access its contents will be considered as an overflow.

## Member Function Documentation

## ◆ base()

libcamera::ByteStreamBuffer::base | ( |  | ) | const
| inline

Retrieve a pointer to the start location of the managed memory buffer.

Returns
  A pointer to the managed memory buffer

## ◆ carveOut()

ByteStreamBuffer libcamera::ByteStreamBuffer::carveOut | ( | size_t | size | ) |

Carve out an area of size bytes into a new ByteStreamBuffer.

Parameters

  [in] | size | The size of the newly created memory buffer

This function carves out an area of size bytes from the buffer into a new ByteStreamBuffer, and returns the new buffer. It operates identically to a read or write access from the point of view of the current buffer, but allows the new buffer to be read or written at a later time after other read or write accesses on the current buffer.

Returns
  A newly created ByteStreamBuffer of size

## ◆ offset()

libcamera::ByteStreamBuffer::offset | ( |  | ) | const
| inline

Retrieve the offset of the current access location from the base.

Returns
  The offset in bytes

## ◆ operator=()

ByteStreamBuffer & libcamera::ByteStreamBuffer::operator= | ( | ByteStreamBuffer && | other | ) |

Replace the contents of the buffer with those of other using move semantics.

Parameters

  [in] | other | The other buffer

After the assignment the other buffer is invalidated. Any attempt to access its contents will be considered as an overflow.

## ◆ overflow()

libcamera::ByteStreamBuffer::overflow | ( |  | ) | const
| inline

Check if the buffer has overflown.

Returns
  True if the buffer has overflow, false otherwise

## ◆ read() [1/3]

template<typename T >

template< typename T > int libcamera::ByteStreamBuffer::read | ( | const Span< T > & | data | ) |
| inline

Read data from the managed memory buffer into Span data.

Parameters

  [out] | data | Span representing the destination memory

Returns
  0 on success, a negative error code otherwise

Return values

  -EACCES | attempting to read from a write buffer
  -ENOSPC | no more space is available in the managed memory buffer

## ◆ read() [2/3]

template<typename T >

template< typename T > const T * libcamera::ByteStreamBuffer::read | ( | size_t | count = `1` | ) |
| inline

Read data from the managed memory buffer without performing a copy.

Parameters

  [in] | count | Number of data items to read

This function reads count elements of type T from the buffer. Unlike the other read variants, it doesn't copy the data but returns a pointer to the first element. If data can't be read for any reason (usually due to reading more data than available), the function returns nullptr.

Returns
  A pointer to the data on success, or nullptr otherwise

## ◆ read() [3/3]

template<typename T >

template< typename T > int libcamera::ByteStreamBuffer::read | ( | T * | t | ) |
| inline

Read data from the managed memory buffer into t.

Parameters

  [out] | t | Pointer to the memory containing the read data

Returns
  0 on success, a negative error code otherwise

Return values

  -EACCES | attempting to read from a write buffer
  -ENOSPC | no more space is available in the managed memory buffer

## ◆ size()

libcamera::ByteStreamBuffer::size | ( |  | ) | const
| inline

Retrieve the size of the managed memory buffer.

Returns
  The size of managed memory buffer

## ◆ skip()

int libcamera::ByteStreamBuffer::skip | ( | size_t | size | ) |

Skip size bytes from the buffer.

Parameters

  [in] | size | The number of bytes to skip

This function skips the next size bytes from the buffer.

Returns
  0 on success, a negative error code otherwise

Return values

  -ENOSPC | no more space is available in the managed memory buffer

## ◆ write() [1/2]

template<typename T >

template< typename T > int libcamera::ByteStreamBuffer::write | ( | const Span< T > & | data | ) |
| inline

Write data to the managed memory buffer.

Parameters

  [in] | data | The data to write to memory

Returns
  0 on success, a negative error code otherwise

Return values

  -EACCES | attempting to write to a read buffer
  -ENOSPC | no more space is available in the managed memory buffer

## ◆ write() [2/2]

template<typename T >

template< typename T > int libcamera::ByteStreamBuffer::write | ( | const T * | t | ) |
| inline

Write t to the managed memory buffer.

Parameters

  [in] | t | The data to write to memory

Returns
  0 on success, a negative error code otherwise

Return values

  -EACCES | attempting to write to a read buffer
  -ENOSPC | no more space is available in the managed memory buffer

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

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