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 ( 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

read() [2/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() [3/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

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

write() [2/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

---

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

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