Skip to content

PassiveRateGroup Component

1. Introduction

Svc::PassiveRateGroup is an passive component that drives a set of components connected to Svc::Sched output ports. It contains an synchronous input Svc::Cycle port that drives all the operations. The component invokes each output port in order, passing an argument specified in the supplied context list. It tracks execution time of the cycle.

2. Requirements

The requirements for Svc::PassiveRateGroup are as follows:

Requirement Description Verification Method
FPRIME-PRG-001 The Svc::PassiveRateGroup component shall be passive and will be driven by an input synchronous port call Inspection, Unit test
FPRIME-PRG-002 The Svc::PassiveRateGroup component shall invoke its output ports in order, passing the value contained in a table based on port number Unit Test
FPRIME-PRG-003 The Svc::PassiveRateGroup component shall track the time required to execute the rate group and report it as telemetry Unit Test
FPRIME-PRG-004 The Svc::PassiveRateGroup component shall track per-port execution times and high water marks when configured Unit Test
FPRIME-PRG-005 The Svc::PassiveRateGroup component shall provide a command to clear statistics and high water marks Unit Test

3. Design

3.1 Context

3.1.1 Component Diagram

The Svc::PassiveRateGroup component has the following component diagram:

PassiveRateGroup Diagram

3.1.2 Ports

The Svc::PassiveRateGroup component uses the following port types:

Port Data Type Name Direction Kind Usage
Svc::Cycle CycleIn Input synchronous Receive a call to run one cycle of the rate group
Svc::Sched RateGroupMemberOut Output n/a Rate group ports
Fw::Cmd CmdDisp Input sync Command receive port
Fw::CmdResponse CmdStatus Output n/a Command response port
Fw::CmdReg CmdReg Output n/a Command registration port
Fw::Tlm Tlm Output n/a Telemetry port
Fw::Time Time Output n/a Time get port

3.2 Functional Description

The Svc::PassiveRateGroup component has one input port that is used to drive all of the processing. The component calls the output ports in order, passing the context from the context list as the port argument.

The component must be configured via configure() with: - A context array of U32 values (one per output port) passed to each rate group member - An optional Os::RawTimeSource specifying which hardware timer to use for execution time measurements (defaults to Os::RAWTIME_DEFAULT)

The component tracks execution time statistics: - Overall rate group cycle time (current and maximum) - Per-port execution times and high water marks (when PassiveRateGroupCfg::PortCycleTime is enabled) - Total cycle count

These statistics can be cleared via the CLEAR_STATISTICS sync command, which resets the maximum cycle time and per-port high water marks to zero (the running cycle count is not cleared). All statistics are protected by lock-free atomic operations, making them ISR-safe and eliminating mutex overhead.

IMPORTANT - RawTimeSource Limitation: The RawTimeSource parameter in configure() only affects the end timestamp of each cycle. The start timestamp (cycleStart) comes from the cycle driver (e.g., RateGroupDriver, LinuxTimer), which constructs its Os::RawTime with RAWTIME_DEFAULT. If you configure a non-default RawTimeSource, the cycle time calculation subtracts timestamps from two different timer sources, producing meaningless results. This feature is only correct when using RAWTIME_DEFAULT (the default), or when the cycle driver is modified to use the same non-default source. There is currently no API to configure the cycle driver's timer source, so non-default configurations require custom cycle driver implementations.

3.2.1 Commands

The Svc::PassiveRateGroup component supports the following commands:

Command Description
CLEAR_STATISTICS Clears port cycle time high water marks and maximum cycle time. Does NOT reset cycle count, which is a running total. Uses lock-free atomic operations for ISR-safe execution.

3.2.2 Telemetry

The Svc::PassiveRateGroup component provides the following telemetry channels:

Channel Type Description
MaxCycleTime U32 Maximum execution time of rate group cycle (microseconds). Cleared by CLEAR_STATISTICS command. Updated only when maximum increases (update on change).
CycleTime U32 Execution time of current cycle (microseconds). Sent every cycle.
CycleCount U32 Running total count of cycles executed. NOT cleared by CLEAR_STATISTICS command. Sent every cycle.
PortCycleTime U32[PassiveRateGroupOutputPorts] Execution time for each port in the most recent cycle (microseconds). Sent every cycle (only when PassiveRateGroupCfg::PortCycleTime is enabled).
PortCycleTimeHWM U32[PassiveRateGroupOutputPorts] High water mark for each port execution time (microseconds). Cleared by CLEAR_STATISTICS command. Updated only when any high water mark increases (update on change). Only available when PassiveRateGroupCfg::PortCycleTime is enabled.

3.3 Scenarios

3.3.1 Rate Group Port Call

As described in the Functional Description section, the Svc::PassiveRateGroup component accepts calls to the CycleIn and invokes the RateGroupMemberOut ports:

Sequence Diagram 

sequenceDiagram
    participant RateGroupDriver
    participant PassiveRateGroup
    participant Callee
    RateGroupDriver ->> PassiveRateGroup: CycleIn
    loop for each callee
        PassiveRateGroup ->> Callee: RateGroupMemberOut[N]
        Callee -->> PassiveRateGroup: 
    end
    PassiveRateGroup -->> RateGroupDriver:

3.4 State

Svc::PassiveRateGroup has no state machines.

3.5 Algorithms

Svc::PassiveRateGroup has no significant algorithms.

4. Change Log

Date Description
2/9/2017 First Draft
8/8/2026 Updated to document CLEAR_STATISTICS command, telemetry channels, and standard ports. Added lock-free atomic operations for all statistics (m_maxTime and per-port HWMs) to provide ISR-safe, race-free concurrent access without mutex overhead.