Skip to content

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

  1. 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:

  1. 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:

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

  2. Call the setup method, passing in an instance P of Svc::FramingProtocol. The setup method does the following:

  3. Store a pointer to P in m_protocol.

  4. 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:

  1. Invoke framedOut, passing in B as the argument.

  2. 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:

Topology 1: Telemetry packets:

tlm

The chanTlm instance sends telemetry packets to the framer instance.

Topology 2: Event packets:

event

The eventLogger instance sends event packets to the framer instance.

Topology 3: File packets:

file

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

  1. fileDownlink sends a buffer PB containing a file packet.

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

  3. 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:

framed

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