[Rate Groups and Timeliness] RateGroups Docs Enhancements #3398
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
… with a static code block
There was a problem hiding this comment.
Pull Request Overview
This PR enhances the RateGroups documentation by correcting a grammatical error and adding a detailed example for a clock prescaler algorithm using Svc core module components.
- Corrected grammatical error in the description.
- Added a new example section illustrating a clock prescaler algorithm, complete with code excerpts.
Files not reviewed (1)
- .github/actions/spelling/expect.txt: Language not supported
|
Let me know if there is something needs to be done to get this approved. |
Co-authored-by: Copilot <[email protected]>
LeStarch
requested changes
Apr 16, 2025
| @@ -25,6 +25,44 @@ 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_**: Recall 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: | |||
There was a problem hiding this comment.
I'd recommend this:
- "Consider a system clock driven at 1000Hz by a crystal oscillator and a rate group needing to run at 100Hz".
| @@ -25,6 +25,44 @@ 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_**: Recall 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. | |||
There was a problem hiding this comment.
- Remove "On the API layers level"
- "Both drivers,
SystemSourceDriver, and theRateGroupDriver, are F´components" - Remove "(e.g., commands, events, and telemetry channels). In this case, the implementation could be taken towards commanding."
| @@ -25,6 +25,44 @@ 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_**: Recall 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). | |||
There was a problem hiding this comment.
Remove "On the hardware level". All rate group items are handled in software.
There was a problem hiding this comment.
I understand the architecture of the RateGroupDrivers. In this part, I was willing to describe what happens during the runtime, which is really hardware and not Rate Groups anymore. Do you recommend a better introductory word?
There was a problem hiding this comment.
So, this explanation is considered a text-based deployment model.
| **_Example_**: Recall 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`). |
There was a problem hiding this comment.
Here I would just state "In the provided Svc/RateGroupDriver this is done by counting up to a configured number of cycles before emiting the divided signal". Link to the source code.
There was a problem hiding this comment.
So, what do you recommend regarding this bullet point? I'd like to describe each variable used, but simply. It was best to do this via a logical implication formula (which summarizes what the algorithm does).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Svccore module.Change Description
The First Change:
I am completely new to F-Prime, but I've some good experience in embedded systems design in general. I was reading the RateGroups and Timeliness documentation when I stepped into a grammatical error, and I've corrected it in this PR.
The Second Change:
At the first glance, I didn't understand what does it mean to provide a clock divider until I looked for the code. That's why I've added this example.
This change involves an example for the algorithms that could be used to implement a Virtual Clock Prescaler (And, I believe there is more). The example simplifies the operations of Cycling and Sampling performed by the core routine
Svc::RateGroupDriver::CycleIn_handler(...).Rationale
I believe this example would be a great add to this page; as it also describes the core algorithm used here to design the
RateGroupDrivercomponents around the System base component. It may immerse the reader, who might be new to F`-prime, into the core quickly, in addition to providing a good example to the RateGroups-Drivers pattern. Let me know if there are requested changes.Future Work
I think referencing more details from the core on the specialized implementation documentation pages would be a good rigorous change, unless these algorithms shall carry breaking future changes. What do you think about that? Also, another thing, maybe examining whether there are other clock prescaler algorithms?