Fw::Buffer Serializable / Fw::BufferGet Port / Fw::BufferSend Port
1 Introduction
This module provides the following elements:
- A type
Fw::Bufferrepresenting a wrapper around a variable-size buffer. This allows for passing a reference to the allocated memory around without a copy. Typically the memory is allocated in a buffer manager or similar component but this is not required. -
A port
Fw::BufferGetfor requesting a buffer of typeFw::Bufferfrom aBufferManagerand similar components. -
A port
Fw::BufferSendfor sending a buffer of typeFw::Bufferfrom one component to another.
2 Design
The Fw::Buffer type wraps a pointer to memory and the size of that memory region. Thus, allowing users to pass the
pointer and size around as a pair without incurring a copy of the data at each step. Note: Fw::Buffer is not safe
to pass outside a given address space.
2.1 The Type Fw::Buffer
Fw::Buffer is a serializable class defining the following (private) fields. These fields are accessed through accessor functions.
| Name | Type | Accessors | Purpose |
|---|---|---|---|
m_bufferData |
U8* |
getData()/setData() |
Pointer to the raw memory wrapped by this buffer |
m_size |
U32 |
getSize()/setSize() |
Size of the raw memory region wrapped by this buffer |
m_context |
U32 |
getContext()/setContext() |
Context of buffer's origin. Used to track buffers created by BufferManager |
m_serialize_repr |
Fw::ExternalSerializeBuffer |
getSerializeRepr() |
Interface for serialization to internal buffer |
A value B of type Fw::Buffer is valid if m_bufferData != nullptr and
m_size > 0; otherwise it is invalid.
The interface function isValid reports whether a buffer is valid.
Calling this function on a buffer B returns true if B is valid, otherwise false.
If a buffer B is invalid, then the pointer returned by B .getData() and the
serialization interface returned by
B .getSerializeRepr() are considered invalid and should not be used.
The getSerializeRepr() function may be used to interact with the wrapped data buffer by serializing types to and from
the data region.
2.2 The Port Fw::BufferGet
As shown in the following diagram, Fw::BufferGet has one argument size of type U32. It returns a value of type
Fw::Buffer. The returned Fw::Buffer must be checked for validity before using.
2.3 The Port Fw::BufferSend
As shown in the following diagram, Fw::BufferSend has one argument fwBuffer of type Fw::Buffer.
3 Usage Notes
Components allocating Fw::Buffer objects may use the m_context field at their discretion. This field is typically
used to track the origin of the buffer for eventual allocation.
When a component fails to allocate memory, it must set
the m_bufferData field to nullptr and/or set the m_size field to zero to indicate that the buffer is invalid.
A receiver of an Fw::Buffer object B must check that B is valid before accessing the
data stored in B.
To check validity, you can call the interface function isValid().
Serializing and Deserializing with Fw::Buffer
Users can obtain a SerializeBuffer, sb, by calling getSerializeRepr(). This serialize buffer is backed by the memory
of the Fw::Buffer and is initially empty. Users can serialize and deserialize through sb to copy to/from the backed
memory.
The state of sb persists as long as the current Fw::Buffer object exists as it is stored as a member. However, all
Fw::Buffer constructors initialize sb to an empty state including the Fw::Buffer copy constructor. Thus, if an
Fw::Buffer is sent through a port call, passed by-value to a function call, or otherwise copied, the state of the new
buffer's sb member is empty.
Serializing to Fw::Buffer
U32 my_data = 10001;
U8 my_byte = 2;
Fw::ExternalSerializeBuffer& sb = my_fw_buffer.getSerializeRepr();
sb.resetSer(); // Return the serialization to the beginning of the memory region
sb.serialize(my_data);
sb.serialize(my_byte);
Since the initial state of sb is empty, deserialization requires setting the size of the data available for
deserialization. This can be done with the sb.setBuffLen() method passing in the Fw::Buffer size.
Deserializing from Fw::Buffer