Svc::Framer (Passive Component)

1. Introduction

Svc::Framer is a passive component. It is part of the standard path for F Prime data downlink. It accepts data packets from service layer components, for example instances of `Svc::TlmChan`, `Svc::ActiveLogger`, or `Svc::FileDownlink`. For each packet P received, it wraps P in a frame F and sends F to a byte stream driver that downlinks frames, for example, `Drv::TcpClient`.

When instantiating Framer, you must provide an implementation of `Svc::FramingProtocol`. This implementation specifies exactly what is in each frame; typically it is a frame header, a data packet, and a hash value. You can use the standard F Prime downlink protocol implementation. This implementation works with the F Prime ground data system (GDS).

Svc::Framer is designed to act alongside instances of the communication adapter interface. In order to work well with communication adapters, Svc::Framer implements the framer status protocol.

2. Assumptions

For any deployment D that uses an instance I of Framer, the framing protocol used with I matches the downlink protocol of any ground system that receives frames from I.

3. Requirements

Requirement	Description	Rationale	Verification Method
SVC-FRAMER-001	`Svc::Framer` shall accept data packets of any type stored in `Fw::Com` buffers.	`Svc::ActiveLogger` and `Svc::ChanTlm` emit packets as `Fw::Com` buffers.	Unit test
SVC-FRAMER-002	`Svc::Framer` shall accept file packets stored in `Fw::Buffer` objects.	`Svc::FileDownlink` emits packets as `Fw::Buffer` objects.	Unit test
SVC-FRAMER-003	`Svc::Framer` shall use an instance of `Svc::FramingProtocol`, supplied when the component is instantiated, to wrap packets in frames.	The purpose of `Svc::Framer` is to frame data packets. Using the `Svc::FramingProtocol` interface allows the same Framer component to operate with different protocols.	Unit test
SVC-FRAMER-004	`Svc::Framer` shall emit a status of `Fw::Success::SUCCESS` when no framed packets were sent in response to incoming buffer.	`Svc::Framer` implements the framer status protocol.	Unit Test
SVC-FRAMER-005	`Svc::Framer` shall forward `Fw::Success` status messages received	`Svc::Framer` implements the framer status protocol.	Unit Test

4. Design

4.1. Component Diagram

The diagram below shows the Framer component.

Framer Component

4.2. Ports

Kind	Name	Port Type	Usage
`guarded input`	`comIn`	`Fw.Com`	Port for receiving data packets of any type stored in statically-sized Fw::Com buffers
`guarded input`	`bufferIn`	`Fw.BufferSend`	Port for receiving file packets stored in dynamically-sized Fw::Buffer objects
`guarded input`	`comStatusIn`	`Fw.SuccessCondition`	Port for receiving status of last send for implementing communication adapter interface protocol
`output`	`bufferDeallocate`	`Fw.BufferSend`	Port for deallocating buffers received on bufferIn, after copying packet data to the frame buffer
`output`	`framedAllocate`	`Fw.BufferGet`	Port for allocating buffers to hold framed data
`output`	`framedOut`	`Drv.ByteStreamSend`	Port for sending buffers containing framed data. Ownership of the buffer passes to the receiver.
`output`	`comStatusOut`	`Fw.SuccessCondition`	Port for sending communication adapter interface protocol status messages

4.3. Derived Classes

Framer is derived from FramerComponentBase as usual. It is also derived (via C++ multiple inheritance) from `Svc::FramingProtocolInterface`. The multiple inheritance makes the Framer instance into the instance of Svc::FramingProtocolInterface that is required to use Svc::FramingProtocol. See below for a description of how Framer implements FramingProtocolInterface.

Here is a class diagram for Framer:

classDiagram
    ObjBase <|-- PassiveComponentBase
    PassiveComponentBase <|-- FramerComponentBase
    FramerComponentBase <|-- Framer
    FramingProtocolInterface <|-- Framer

4.4. State

Framer maintains the following state:

m_protocol: A pointer to the implementation of FramingProtocol used for framing.

4.5. Header File Configuration

None.

4.6. Runtime Setup

To set up an instance of Framer, you do the following:

Call the constructor and the init method in the usual way for an F Prime passive component.

Call the setup method, passing in an instance P of Svc::FramingProtocol. The setup method does the following:
1. Store a pointer to P in m_protocol.
1. Pass *this into the setup method for P. As noted above, *this is the instance of Svc::FramingProtocolInterface used by P.

For an example of setting up a Framer instance, see the downlink instance in Ref/Top/instances.fpp.

4.7. Port Handlers

4.7.1. comIn

The comIn port handler receive a reference to an Fw::Com buffer B and an integer context value. It calls the frame method of m_protocol, passing in the address and length of B and the packet type Fw::ComPacket::FW_PACKET_UNKNOWN.

4.7.2. bufferIn

The bufferIn port handler receives a reference to an Fw::Buffer object B. It calls the frame method of m_protocol, passing in the data address and size of B and the packet type Fw::ComPacket::FW_PACKET_FILE.

4.7.2. comStatusIn

The comStatusIn port handler receives com status messages and forwards them out comStatusOut.

4.8. Implementation of Svc::FramingProtocolInterface

4.8.1. allocate

The implementation of allocate invokes framedAllocate.

4.8.2. send

The implementation of send takes a reference to an Fw::Buffer B representing framed data and does the following:

Invoke framedOut, passing in B as the argument.

Check the return status of the invocation. If the return status is not Drv::SendStatus::SEND_OK, then use Fw::Logger::log to log an error message. Don't send an event report in this case, because downlink is apparently not working.

5. Ground Interface

None.

If an error occurs, Framer writes to the system log. The rationale is that if something is wrong with the framing, then downlink of events is unlikely to work.

6. Example Uses

6.1. Topology Diagrams

The following topology diagrams show how to connect Svc::Framer to a telemetry database, an event collector, a file downlink component, and a byte stream driver. The diagrams use the following instances:

comm: An instance of `Drv::ByteStreamDriverModel`, for example `Drv::TcpClient`.
buffMgr: An instance of `Svc::BufferManager`
fileDownlink: An instance of `Svc::FileDownlink`.
framer: An instance of Svc::Framer.
chanTlm: An instance of `Svc::TlmChan`.
eventLogger: An instance of `Svc::ActiveLogger`.

Topology 1: Telemetry packets:

The chanTlm instance sends telemetry packets to the framer instance.

Topology 2: Event packets:

The eventLogger instance sends event packets to the framer instance.

Topology 3: File packets:

The fileDownlink instance sends a sequence of file packets, representing a complete file, to the framer instance. The sending happens in the following sequence:

fileDownlink sends a buffer PB containing a file packet.

framer receives and processes PB. When it is done, it returns PB to fileDownlink.

Upon receipt of PB, if another file packet is available, fileDownlink sends it.

Exchanging the buffer controls the rate at which fileDownlink sends file packets. It ensures that the rate does not exceed the rate at which framer can handle the packets.

Topology 4: Framed data:

framer allocates frame buffers from buffMgr. It sends buffers containing frames to comm. comm processes the buffers and sends them to buffMgr for deallocation.

6.2. Sequence Diagrams

In the following diagrams, open vertical rectangles represent threads. Vertical dashed lines represent component code. Solid horizontal arrows represent synchronous port invocations, and open horizontal arrows represent asynchronous port invocations.

These diagrams assume that, in the implementation of Svc::FramingProtocol passed in at initialization, each downlink frame contains a single packet. This is a common use case; for example, the F Prime standard downlink protocol is implemented this way.

6.2.1. Sending a Telemetry Packet

The following diagram shows what happens when chanTlm sends a telemetry packet to framer.

sequenceDiagram
    activate chanTlm
    chanTlm->>framer: Send telemetry packet P [comIn]
    framer->>buffMgr: Allocate frame buffer B [framedAllocate]
    buffMgr-->>framer: Return B
    framer->>framer: Frame P into B
    framer-)comm: Send B [framedOut]
    comm->>comm: Downlink frame
    comm->>buffMgr: Deallocate B
    buffMgr-->>comm: 
    comm-->>framer: 
    framer-->>chanTlm: 
    deactivate chanTlm

6.2.2. Sending an Event Packet

The following diagram shows what happens when eventLogger sends an event packet to framer.

sequenceDiagram
    activate eventLogger
    eventLogger->>framer: Send event packet P [comIn]
    framer->>buffMgr: Allocate frame buffer B [framedAllocate]
    buffMgr-->>framer: Return B
    framer->>framer: Frame P into B
    framer-)comm: Send B [framedOut]
    comm->>comm: Downlink frame
    comm->>buffMgr: Deallocate B
    buffMgr-->>comm: 
    comm-->>framer: 
    framer-->>eventLogger: 
    deactivate eventLogger

6.2.3. Sending a File Packet

The following diagram shows what happens when fileDownlink sends a file packet to framer.

sequenceDiagram
    activate fileDownlink
    fileDownlink->>framer: Send file packet buffer PB [bufferIn]
    framer->>buffMgr: Allocate frame buffer B [framedAllocate]
    buffMgr-->>framer: Return B
    framer->>framer: Frame P into B
    framer-)comm: Send B [framedOut]
    comm->>comm: Downlink frame
    comm->>buffMgr: Deallocate B
    buffMgr-->>comm: 
    comm-->>framer: 
    framer->>fileDownlink: Return PB [bufferDeallocate]
    fileDownlink-->>framer: 
    framer-->>fileDownlink: 
    deactivate fileDownlink