From 6433f694c794c342dc8e576fb6c968e98292c615 Mon Sep 17 00:00:00 2001 From: "Pavly Gerges (pavl_g)" <60224159+pavly-gerges@users.noreply.github.com> Date: Fri, 26 Sep 2025 17:01:57 -0500 Subject: [PATCH] RateGroup Docs Enhancements (#4196) * Update rate-group.md * Update expect.txt * Added a word to the dictionary. --- .github/actions/spelling/expect.txt | 1 + docs/user-manual/design-patterns/rate-group.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index c170a36734..c44f1165a6 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -499,6 +499,7 @@ PORTOUT PORTSELECTOR ppandian pregen +prescaler prioritization PRIORITYQUEUE prm diff --git a/docs/user-manual/design-patterns/rate-group.md b/docs/user-manual/design-patterns/rate-group.md index c4d3cdfdd7..6203dc9d60 100644 --- a/docs/user-manual/design-patterns/rate-group.md +++ b/docs/user-manual/design-patterns/rate-group.md @@ -13,7 +13,7 @@ central rate group driver and achieve their rates by dividing the incoming signa The `RateGroupDriver` component is the source of the "clock" or tick for the various rate groups. It is usually driven off a system timing interrupt or some other reliable clock source, and it performs the clock divider functionality to -produces a series of slower repeating tick signals that are sent to the rate groups attached to it. +produce a series of slower repeating tick signals that are sent to the rate groups attached to it. ### System Clock Sources @@ -25,6 +25,18 @@ system clock and the port call to rate group driver's `CycleIn` port. The reference application calls the `CycleIn` port followed by a sleep for the system clock time within a while loop to simulate a system-driven clock. +**_Example_**: Consider a crystal oscillator running at 1000 HZ (or 1 MHZ), then a system clock source would sample each 1MHZ. Recall that a `RateGroupDriver` is registered to this system clock source sampler that requires to be updated at a rate of 100HZ; therefore the following applies: +* On the API layers level, both drivers; the `SystemSourceDriver`, and the `RateGroupDriver` shall be implementations of F' components; thus they could only communicate via ports (e.g., commands, events, and telemetry channels). In this case, the implementation could be taken towards commanding. +* On the hardware level, the `SystemSourceDriver` shall use a clock divider that drives the `RateGroupDriver` each $$\frac{100HZ}{1MHZ}$$ of the system source sampler (i.e., at a rate of $$\frac{1}{10}$$ of the system source sampler). +* On the hardware implementation level, this could be done via many approaches; a counter algorithm (that triggers an interrupt when reaching 100 cycles resetting the `numberOfCycles` each second) can suffice or a more complex modular arithmetics algorithm could be used (e.g., $$((ticks\ mod\ rate)\ ==\ offset) \implies CycleOut$$; where `ticks` represents the current system virtual clocks, `rate` represents the `RateGroupDriver` required frequency, and `offset` represents the remainder of the value at which sampling shall occur when the system clock `ticks` reaches the requested `rate`; Zero `offset` means that the system source sampler will sample this driver when it reaches an integer multiple of its requested `rate`). +* The algorithm utilized here provides a software-based analogous activity to [the clock prescaler digital circuits](https://en.wikipedia.org/wiki/Prescaler). + +> [!NOTE] +> **Linking with the `Svc` core module:** +> * Here is the simple algorithm of `Svc::RateGroupDriver` implemented by the core libraries; where values captured from this algorithm can be encapsulated further in a `Divider` structure. +> * This is essentially a variant of rate-controlled publish-subscriber pattern that samples the registered `RateGroupDriver` components by their requested sampling rate via their port channels: See [the Core Implementation `RateGroupDriver::CycleIn_handler(...)`](https://github.com/nasa/fprime/blob/devel/Svc/RateGroupDriver/RateGroupDriver.cpp). +> + ## Passive and Active Rate Groups The passive and active rate groups receive the input source signal or "tick" at the divided rate as provided from the @@ -76,4 +88,4 @@ The topology connections for rate groups can be seen here: [Rate Group Topology](https://github.com/nasa/fprime/blob/ddcb2ec138645da34cd4c67f250b67ee8bc67b26/Ref/Top/topology.fpp#L97-L124) A sample schedule handler can be found here: -[Sample Schedule Handler](https://github.com/nasa/fprime/blob/ddcb2ec138645da34cd4c67f250b67ee8bc67b26/Ref/SignalGen/SignalGen.cpp#L98-L140) \ No newline at end of file +[Sample Schedule Handler](https://github.com/nasa/fprime/blob/ddcb2ec138645da34cd4c67f250b67ee8bc67b26/Ref/SignalGen/SignalGen.cpp#L98-L140)