libcamera  v0.3.1+12-19bbca3c
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...
 
ByteStreamBufferoperator= (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]baseThe address of the memory area to wrap
[in]sizeThe 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]baseThe address of the memory area to wrap
[in]sizeThe 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]otherThe 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]sizeThe 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]otherThe 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]tPointer to the memory containing the read data
Returns
0 on success, a negative error code otherwise
Return values
-EACCESattempting to read from a write buffer
-ENOSPCno 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]dataSpan representing the destination memory
Returns
0 on success, a negative error code otherwise
Return values
-EACCESattempting to read from a write buffer
-ENOSPCno 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]countNumber 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]sizeThe 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
-ENOSPCno 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]tThe data to write to memory
Returns
0 on success, a negative error code otherwise
Return values
-EACCESattempting to write to a read buffer
-ENOSPCno 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]dataThe data to write to memory
Returns
0 on success, a negative error code otherwise
Return values
-EACCESattempting to write to a read buffer
-ENOSPCno more space is available in the managed memory buffer

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