Requesting Community Feedback: Refactoring the Downlink Interface

[thomas-bc]

Hello dear community!

The team has been slowly converging towards an idea, and we would like to share it with you and get your feedback on it.

In one sentence: we are considering refactoring Svc.ComQueue's interface and removing the contract on data format, to make it easier for projects to define and use project-configurable APIDs, and simplifying the configuration.

Background

The Svc.ComQueue is a central component in our downlink stack. Application layer components that want to send data out of the system (e.g. TlmPacketizer, EventManager, FileDownlink, or project-specific components that want to send packets out to the radio) queue up messages through Svc.ComQueue.

Svc.ComQueue queues up messages (of type Fw.Buffer or Fw.Com) and sends sends them to the radio, through the framers for framing. However, working with ComQueue is not straightforward, and it expects what one could call the "F Prime packet layout" ( | PacketDescriptor | Payload |).

Click to expand for a long tangent on more details on the current ComQueue... not essential to this proposal

How to setup a component to interface with Svc.ComQueue is not super well documented, and relies on a process that has grown to be a bit complex, with needing to keep track port indices on ComQueue to assign priorities for different types of messages, needing to stamp out a PacketDescriptor token (==APID in CCSDS) at the front of the payload, etc. This is not ideal, and not user-friendly.

In my view, Svc.ComQueue is actually a Svc.FprimePacketQueue, where F Prime packet == | PacketDescriptor | Payload |. ComQueue will only function if the data is laid out this way.

We are also duplicating data in that the Packet Descriptor is repeated twice in each frame when using CCSDS: once in the Space Packet header (APID field), and once in the payload which is essentially an "F Prime Packet" format.

Historically, we've used the F Prime Protocol and a custom F Prime "packet" format (not much docs for that unfortunately, which is a big motivation for trying to clean that up and document it nicely), where PacketDescriptor tokens are stamped out at the front of the payload to indicate what kind of payload it is (telemetry, event, file etc.). This is essentially a very minimalistic implementation of a protocol stack, and we can draw equivalences with the CCSDS protocol stack. PacketDescriptor == Space Packet APID, F Prime Protocol == CCSDS Data Link Layer protocol (TC/TM/AOS/USLP).

When implementing the CCSDS protocols in F Prime, we've tried to introduce minimal breaking changes, and so we've encapsulated the F Prime "packet" within a CCSDS Space Packet. We've also re-used the Svc.ComQueue component so that the migration would be transparent to the user. We've built on top of existing infrastructure that is solid, and that is great. But that was at the cost of some redundancy and added complexity.

The Proposal

I propose that we refactor the interface between the application layer and the Comms(Downlink) layer through a tweaked version of the Svc.ComQueue, that I suggest we call Svc.DownlinkQueue (better name TBD?).

Design Goals

• Svc.DownlinkQueue shall be agnostic to the layout of the payload. It shouldn't even need to look at it, just pass it along.
• Any component shall be able to queue up a payload Fw.Buffer for downlink by connecting to Svc.DownlinkQueue.
• Input port shall provide two arguments, payload: Fw.Buffer and contextData: ComCfg.FrameContext that contains at least a PacketDescriptor (==APID in CCSDS) indicating the type/source of the payload. (see ComCfg.FrameContext)
• Extending on the contextData: Users (i.e. component connecting to DownlinkQueue) shall be free to provide additional context (or hints ?) such as priority, Virtual Channel ID for CCSDS, etc. — with the understanding that different protocol implementations may or may not support that additional context.
• User API shall be clearly documented from the get-go

Proposed Changes

The main change is to pull that contextData: ComCfg.FrameContext argument up to the application interface level. Today, the contextData is created within the ComQueue based on the payload token (which is basically an implicit version of contextData). It is not available to the user.

I believe we should be able to leverage much of the existing Svc.ComQueue implementation, and just refactor the user interface along with queuing up the context object alongside the payload. Then, it can be passed down to the framers, which are already setup to use ComCfg.FrameContext for framing.

Examples of what that would look like from the "user" side, for example in FileDownlink.cpp:

// FileDownlink.cpp
-    // Serialize the packet descriptor FW_PACKET_FILE to the buffer
-    Fw::SerializeStatus status = buffer.getSerializer().serializeFrom(static_cast<FwPacketDescriptorType>(Fw::ComPacketType::FW_PACKET_FILE));
-    Fw::Buffer offsetBuffer(buffer.getData() + sizeof(FwPacketDescriptorType),
-                            buffer.getSize() - static_cast<Fw::Buffer::SizeType>(sizeof(FwPacketDescriptorType)));
-    status = filePacket.toBuffer(offsetBuffer);
-    this->bufferSendOut_out(0, buffer);
+    ComCfg::FrameContext context;
+    context.apid = ComCfg::Apid::FW_PACKET_FILE;
+    this->downlinkQueue_out(0, buffer, context);

In projects, you could add APIDs to the ComCfg.Apid configuration, and send packets out just the same, with your project-configured APIDs.

This makes the system substantially easier to follow and extend:

• Users can easily send out payloads with a project-selected APID. All APIDs are easily traceable in the code.
• Downstream protocols can handle project-specified context at will. In the default CCSDS config, we could for example add multiple priorities/queues for different Virtual Channels and/or APIDs.

Long term vision & possiblities

Jotting down a few thoughts:

• I could see us long-term moving towards having APIDs in the FPP model. A component in FPP could register APIDs that it wants to send/listen for, and FPP can autocode the sendPayloadWithApid() ports and the receive_APID_xyz_handler() handlers. The above proposal is entirely compatible with this and is a step towards enabling this.
• Virtual Channel usage and prioritization: need to be figured out if/how we want to support this. Currently, the default F Prime stack uses a single virtual channel because we haven't felt the need for another one. If we do, it can likely can be an extension of the DownlinkQueue. This is TBD - I'd gladly get feedback on this.
• Implementation of the CCSDS standard "Space Packet Service"/"Octet String Service" -> with a subtopology, we can pack together the Svc.DownlinkQueue together with the Svc.ApidManager and the SpacePacketFramer/Deframer and this would provide exactly what the CCSDS standard defines as a "Space Packet Service" and "Octet String Service" (ref).

Request for Feedback

I'm eager to get as much feedback as possible on this! I realize different organizations may have a different approach to all those things. So I'm curious to hear about your thoughts, if maybe there are things I overlooked, use-cases that aren't covered, etc.

A few specific questions for the community:

1. The above proposal sound really neat in my opinion, but it does have the potential to bias some of our core components and framework design towards CCSDS concepts if we're not careful. Is this good or bad? There are conflicting opinions. Some projects may not want to use CCSDS and prioritize hyper-performance on some communications channels. At JPL, it sounds like people are leaning very much towards being CCSDS-agnostic.
2. Thoughts on if/how to use Virtual Channels?
3. Thoughts on APIDs in the FPP model?

CC'ing a few people that may be interested
@Willmac16 @etiennecollin @gmarchetx @keck-in-space @timcanham @LeStarch

[ebenezerarunkumar]

Great Idea! My team would definitely benefit from it! I think it would add flexibility for users to adopt a more CCSDS centric approach (if they so wished) while also allowing users to implement their own logic as needed

[thomas-bc]

Opened a feature request going in that direction: #4909

Decided to only include the PacketDescriptor for now (as opposed to full FrameContext object) to keep the interface simple and agnostic to the underlying Comms implementation. Clear contract, clear separation between App layer and Comms layer.