Svc::FrameAccumulator
The Svc::FrameAccumulator
component accumulates a stream of data (sequence of Fw::Buffer objects) to extract full frames from.
The Svc::FrameAccumulator
accepts as input a sequence of byte buffers, which typically come from a ground data system via a ByteStreamDriver. It extracts the frames from the sequence of buffers and emits them on the frameOut
output port.
Internals
Overview and configuration
The Svc::FrameAccumulator
accumulates the Fw::Buffer objects into a circular buffer (Utils::CircularBuffer).
The component must be configured with a Svc::FrameDetector
which is responsible for detecting frames in the circular buffer. An implementation of this for the F´ communications protocol is provided by Svc::FrameDetectors::FprimeFrameDetector
.
The uplink frames need not be aligned on the buffer boundaries, and each frame may span one or more buffers.
Frame detection
The Svc::FrameAccumulator
receives Fw::Buffer
objects on its dataIn
input port. These buffers are accumulated in a Utils::CircularBuffer
. Every time a new buffer is accumulated into the circular buffer, the Svc::FrameAccumulator
enters a loop to detect()
a frame within the circular buffer, starting at the current head of the circular buffer. The Svc::FrameDetector
returns one of three results:
NO_FRAME_DETECTED
: indicates no valid frame is present at the head of the circular buffer (for example, start word does not match the current head of the circular buffer). TheSvc::FrameAccumulator
rotates the circular buffer one byte and loops over todetect()
again, or break the loop if the circular buffer is exhausted.FRAME_DETECTED
: indicates there is a frame at the current head of the circular buffer. TheSvc::FrameAccumulator
allocates a newFw::Buffer
object to hold the frame, copies the detected frame from the circular buffer into the newFw::Buffer
object, and emits the newFw::Buffer
object (containing the frame) on itsframeOut
output port. TheSvc::FrameAccumulator
then rotates the circular buffer to remove the data that was just extracted, and deallocates the originalFw::Buffer
that was received on thedataIn
input port.MORE_DATA_NEEDED
: indicates that more data is needed to determine whether there is a valid frame. TheSvc::FrameAccumulator
deallocates the originalFw::Buffer
that was received on thedataIn
input port and halts execution, effectively waiting for the nextFw::Buffer
to be received on thedataIn
input port.
sequenceDiagram
participant I as Input
box Grey FrameAccumulator
participant A as Accumulator
participant D as Detector
end
I-->>A: Fw::Buffer
activate A
A-->A: Serialize into RingBuffer
loop
A-->>D: detect()
alt MORE_DATA_NEEDED
A-->A: break
else NO_FRAME_DETECTED
A-->>A: ring.rotate(1)
else FRAME_DETECTED
create participant Z as Output
A-->>Z: Frame
end
end
deactivate A
destroy O
Cleanup
The cleanup()
method must be called to deallocate the memory used by the Svc::FrameAccumulator
component safely before shutdown. This method deallocates the circular buffer that was set up during the configure()
method.
Usage Examples
The Svc::FrameAccumulator
component is used in the uplink stack of many reference F´ application such as the tutorials source code. The below diagram shows the canonical configuration in which it is used.
Class Diagram
classDiagram
class FrameAccumulator~PassiveComponent~ {
+ void configure(FrameDetector& detector, FwEnumStoreType allocationId, Fw::MemAllocator& allocator, FwSizeType store_size)
+ void dataIn_handler(FwIndexType portNum, Fw::Buffer& recvBuffer, const Drv::RecvStatus& recvStatus)
+ void processBuffer(Fw::Buffer& buffer)
+ void processRing()
}
Requirements
Requirement | Description | Rationale | Verification Method |
---|---|---|---|
SVC-FRAME-ACCUMULATOR-001 | Svc::FrameAccumulator shall accumulate a sequence of byte buffers until a full frame is received |
FrameAccumulator is designed to re-assemble frames from sequence of bytes | Unit test |
SVC-FRAME-ACCUMULATOR-002 | Svc::FrameAccumulator shall detect once the accumulated buffers form a full frame and emit said frame |
Pass frames to other parts of the system | Unit test |
SVC-FRAME-ACCUMULATOR-003 | Svc::FrameAccumulator shall accept byte buffers containing frames that are not aligned on a buffer boundary. |
For flexibility, we do not require that the frames be aligned on a buffer boundary. | Unit test |
SVC-FRAME-ACCUMULATOR-004 | Svc::FrameAccumulator shall accept byte buffers containing frames that span one or more buffers. |
For flexibility, we do not require each frame to fit in a single buffer. | Unit test |
Port Descriptions
Kind | Name | Type | Description |
---|---|---|---|
guarded input |
dataIn | Drv.ByteStreamRecv |
Receives raw data from a ByteStreamDriver, ComStub, or other buffer producing component |
output |
frameOut | Fw.DataWithContext |
Port for sending an extracted frame out |
output |
bufferAllocate | Fw.BufferGet |
Port for allocating buffer to hold extracted frame |
output |
bufferDeallocate | Fw.BufferSend |
Port for deallocating buffers received on dataIn. |