Skip to content

Commit

Permalink
Merge branch 'main' into FP-2784_fpp_changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@bocchino
bocchino committed Oct 2, 2024
2 parents 3f37e37 + 446b30b commit ebc9de7
Show file tree
Hide file tree
Showing 4 changed files with 181 additions and 40 deletions.
2 changes: 1 addition & 1 deletion docs/fpp-spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10527,7 +10527,7 @@ <h3 id="Analysis-and-Translation_Translation-Tools">22.4. Translation Tools</h3>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-10-02 10:58:51 -0700
Last updated 2024-10-02 15:33:46 -0700
</div>
</div>
<script src="code-prettify/run_prettify.js"></script>
Expand Down
116 changes: 95 additions & 21 deletions docs/fpp-users-guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -610,6 +610,7 @@ <h1>The F Prime Prime (FPP) User&#8217;s Guide, v2.2.0</h1>
<li><a href="#Defining-Component-Instances_Init-Specifiers_Writing-Init-Specifiers">11.3.2. Writing Init Specifiers</a></li>
</ul>
</li>
<li><a href="#Defining-Component-Instances_Generation-of-Names">11.4. Generation of Names</a></li>
</ul>
</li>
<li><a href="#Defining-Topologies">12. Defining Topologies</a>
Expand Down Expand Up @@ -7105,7 +7106,9 @@ <h3 id="Defining-Component-Instances_Specifying-the-Implementation">11.2. Specif
type if its qualified C&#43;&#43; class name matches the qualified
name of the FPP component.
For example, the C&#43;&#43; class name <code>A::B</code> matches the FPP component
name <code>A.B</code>.</p>
name <code>A.B</code>.
More generally, modules in FPP become namespaces in C&#43;&#43;, so
dot qualifiers in FPP become double-colon qualifiers in C&#43;&#43;.</p>
</div>
<div class="paragraph">
<p>If the names do not match, then you must provide the type
Expand Down Expand Up @@ -7513,7 +7516,7 @@ <h4 id="Defining-Component-Instances_Init-Specifiers_Writing-Init-Specifiers">11
cmdSeq.allocateBuffer(
0,
Allocation::mallocator,
ConfigConstants::cmdSeq::BUFFER_SIZE
ConfigConstants::SystemReference_cmdSeq::BUFFER_SIZE
);
"""

Expand All @@ -7527,7 +7530,17 @@ <h4 id="Defining-Component-Instances_Init-Specifiers_Writing-Init-Specifiers">11
<div class="paragraph">
<p>The code for <code>configConstants</code> provides a constant <code>BUFFER_SIZE</code>
that is used in the <code>configComponents</code> phase.
The code for <code>configComponents</code> calls <code>allocateBuffer</code>, passing
The code generator places this code snippet in the
namespace <code>ConfigConstants::SystemReference_cmdSeq</code>.
Notice that the second part of the namespace uses the
fully qualified name <code>SystemReference::cmdSeq</code>, and it replaces
the double colon <code>::</code> with an underscore <code>_</code> to generate
the name.
We will explain this behavior further in the section on
<a href="#Defining-Component-Instances_Generation-of-Names">generation of names</a>.</p>
</div>
<div class="paragraph">
<p>The code for <code>configComponents</code> calls <code>allocateBuffer</code>, passing
in an allocator object that is declared elsewhere.
(In the section on
<a href="#Writing-C-Plus-Plus-Implementations_Implementing-Deployments">implementing deployments</a>, we will explain where this allocator
Expand Down Expand Up @@ -7584,6 +7597,67 @@ <h4 id="Defining-Component-Instances_Init-Specifiers_Writing-Init-Specifiers">11
</div>
</div>
</div>
<div class="sect2">
<h3 id="Defining-Component-Instances_Generation-of-Names">11.4. Generation of Names</h3>
<div class="paragraph">
<p>FPP uses the following rules to generate the names associated with
component instances.
First, as explained in the section on
<a href="#Defining-Component-Instances_Specifying-the-Implementation">specifying the implementation</a>,
a component type <code>M.C</code> in FPP becomes the type <code>M::C</code> in C&#43;&#43;.
Here <code>C</code> is a C&#43;&#43; class defined in namespace <code>M</code> that
implements the behavior of component <code>C</code>.</p>
</div>
<div class="paragraph">
<p>Second, a component instance <em>I</em> defined in module <em>N</em> becomes
a C&#43;&#43; variable <em>I</em> defined in namespace <em>N</em>.
For example, this FPP code</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">module N {

instance i: M.C base id 0x100

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>becomes this code in the generated C&#43;&#43;:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="c++">namespace N {

M::C i;

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>So the fully qualified name of the instance is <code>N.i</code> in FPP and <code>N::i</code>
in C&#43;&#43;.</p>
</div>
<div class="paragraph">
<p>Third, all other code related to instances is generated in the namespace of the
top-level implementation.
For example, in the System Reference example from the previous section,
the top-level implementation is in the namespace <code>SystemReference</code>, so
the code for configuring constants is generated in that namespace.
We will have more to say about the top-level implementation in
the section on <a href="#Writing-C-Plus-Plus-Implementations_Implementing-Deployments">implementing deployments</a>.</p>
</div>
<div class="paragraph">
<p>Fourth, when generating the name of a constant associated with an instance,
FPP uses the fully-qualified name of the instance, and it replaces
the dots (in FPP) or the colons (in C&#43;&#43;) with underscores.
For example, as discussed in the previous section, the configuration
constants for the instance <code>SystemReference::cmdSeq</code> are placed in
the namespace <code>ConfigConstants::SystemReference_cmdSeq</code>.
This namespace, in turn, is placed in the namespace <code>SystemReference</code>
according to the previous paragraph.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
Expand Down Expand Up @@ -12278,8 +12352,8 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Application
comDriver.startSocketTask(
name,
true,
ConfigConstants::comDriver::PRIORITY,
ConfigConstants::comDriver::STACK_SIZE
ConfigConstants::SystemReference_comDriver::PRIORITY,
ConfigConstants::SystemReference_comDriver::STACK_SIZE
);
}
"""</code></pre>
Expand Down Expand Up @@ -12345,21 +12419,21 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Application

// Health ping entries
namespace PingEntries {
namespace blockDrv { enum { WARN = 3, FATAL = 5 }; }
namespace chanTlm { enum { WARN = 3, FATAL = 5 }; }
namespace cmdDisp { enum { WARN = 3, FATAL = 5 }; }
namespace cmdSeq { enum { WARN = 3, FATAL = 5 }; }
namespace eventLogger { enum { WARN = 3, FATAL = 5 }; }
namespace fileDownlink { enum { WARN = 3, FATAL = 5 }; }
namespace fileManager { enum { WARN = 3, FATAL = 5 }; }
namespace fileUplink { enum { WARN = 3, FATAL = 5 }; }
namespace imageProcessor { enum {WARN = 3, FATAL = 5}; }
namespace prmDb { enum { WARN = 3, FATAL = 5 }; }
namespace processedImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace rateGroup1Comp { enum { WARN = 3, FATAL = 5 }; }
namespace rateGroup2Comp { enum { WARN = 3, FATAL = 5 }; }
namespace rateGroup3Comp { enum { WARN = 3, FATAL = 5 }; }
namespace saveImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_blockDrv { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_chanTlm { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_cmdDisp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_cmdSeq { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_eventLogger { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileDownlink { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileManager { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileUplink { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_imageProcessor { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_prmDb { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_processedImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_rateGroup1Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_rateGroup2Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_rateGroup3Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_saveImageBufferLogger { enum { WARN = 3, FATAL = 5 }; }
}

}</code></pre>
Expand Down Expand Up @@ -12531,7 +12605,7 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Public-Symb
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-10-02 10:59:26 -0700
Last updated 2024-10-02 15:34:21 -0700
</div>
</div>
<script src="code-prettify/run_prettify.js"></script>
Expand Down
69 changes: 68 additions & 1 deletion docs/users-guide/Defining-Component-Instances.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -339,6 +339,8 @@ type if its qualified {cpp} class name matches the qualified
name of the FPP component.
For example, the {cpp} class name `A::B` matches the FPP component
name `A.B`.
More generally, modules in FPP become namespaces in {cpp}, so
dot qualifiers in FPP become double-colon qualifiers in {cpp}.

If the names do not match, then you must provide the type
associated with the implementation.
Expand Down Expand Up @@ -669,7 +671,7 @@ instance cmdSeq: Svc.CmdSequencer base id 0x0700 \
cmdSeq.allocateBuffer(
0,
Allocation::mallocator,
ConfigConstants::cmdSeq::BUFFER_SIZE
ConfigConstants::SystemReference_cmdSeq::BUFFER_SIZE
);
"""
Expand All @@ -682,6 +684,15 @@ instance cmdSeq: Svc.CmdSequencer base id 0x0700 \

The code for `configConstants` provides a constant `BUFFER_SIZE`
that is used in the `configComponents` phase.
The code generator places this code snippet in the
namespace `ConfigConstants::SystemReference_cmdSeq`.
Notice that the second part of the namespace uses the
fully qualified name `SystemReference::cmdSeq`, and it replaces
the double colon `::` with an underscore `_` to generate
the name.
We will explain this behavior further in the section on
<<Defining-Component-Instances_Generation-of-Names,generation of names>>.

The code for `configComponents` calls `allocateBuffer`, passing
in an allocator object that is declared elsewhere.
(In the section on
Expand Down Expand Up @@ -734,3 +745,59 @@ For more examples of init specifiers in action, see the rest of
the file `SystemReference/Top/instances.fpp` in the F Prime repository.
In particular, the init specifiers for the `comDriver` instance
use the `state` value that we just mentioned.

=== Generation of Names

FPP uses the following rules to generate the names associated with
component instances.
First, as explained in the section on
<<Defining-Component-Instances_Specifying-the-Implementation,
specifying the implementation>>,
a component type `M.C` in FPP becomes the type `M::C` in {cpp}.
Here `C` is a {cpp} class defined in namespace `M` that
implements the behavior of component `C`.

Second, a component instance _I_ defined in module _N_ becomes
a {cpp} variable _I_ defined in namespace _N_.
For example, this FPP code

[source,fpp]
--------
module N {
instance i: M.C base id 0x100
}
--------

becomes this code in the generated {cpp}:

[source,c++]
----
namespace N {
M::C i;
}
----

So the fully qualified name of the instance is `N.i` in FPP and `N::i`
in {cpp}.

Third, all other code related to instances is generated in the namespace of the
top-level implementation.
For example, in the System Reference example from the previous section,
the top-level implementation is in the namespace `SystemReference`, so
the code for configuring constants is generated in that namespace.
We will have more to say about the top-level implementation in
the section on <<Writing-C-Plus-Plus-Implementations_Implementing-Deployments,
implementing deployments>>.

Fourth, when generating the name of a constant associated with an instance,
FPP uses the fully-qualified name of the instance, and it replaces
the dots (in FPP) or the colons (in {cpp}) with underscores.
For example, as discussed in the previous section, the configuration
constants for the instance `SystemReference::cmdSeq` are placed in
the namespace `ConfigConstants::SystemReference_cmdSeq`.
This namespace, in turn, is placed in the namespace `SystemReference`
according to the previous paragraph.
34 changes: 17 additions & 17 deletions docs/users-guide/Writing-C-Plus-Plus-Implementations.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -286,8 +286,8 @@ if (state.hostName != nullptr && state.portNumber != 0) {
comDriver.startSocketTask(
name,
true,
ConfigConstants::comDriver::PRIORITY,
ConfigConstants::comDriver::STACK_SIZE
ConfigConstants::SystemReference_comDriver::PRIORITY,
ConfigConstants::SystemReference_comDriver::STACK_SIZE
);
}
"""
Expand Down Expand Up @@ -341,21 +341,21 @@ namespace SystemReference {
// Health ping entries
namespace PingEntries {
namespace blockDrv { enum { WARN = 3, FATAL = 5 }; }
namespace chanTlm { enum { WARN = 3, FATAL = 5 }; }
namespace cmdDisp { enum { WARN = 3, FATAL = 5 }; }
namespace cmdSeq { enum { WARN = 3, FATAL = 5 }; }
namespace eventLogger { enum { WARN = 3, FATAL = 5 }; }
namespace fileDownlink { enum { WARN = 3, FATAL = 5 }; }
namespace fileManager { enum { WARN = 3, FATAL = 5 }; }
namespace fileUplink { enum { WARN = 3, FATAL = 5 }; }
namespace imageProcessor { enum {WARN = 3, FATAL = 5}; }
namespace prmDb { enum { WARN = 3, FATAL = 5 }; }
namespace processedImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace rateGroup1Comp { enum { WARN = 3, FATAL = 5 }; }
namespace rateGroup2Comp { enum { WARN = 3, FATAL = 5 }; }
namespace rateGroup3Comp { enum { WARN = 3, FATAL = 5 }; }
namespace saveImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_blockDrv { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_chanTlm { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_cmdDisp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_cmdSeq { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_eventLogger { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileDownlink { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileManager { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_fileUplink { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_imageProcessor { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_prmDb { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_processedImageBufferLogger { enum {WARN = 3, FATAL = 5}; }
namespace SystemReference_rateGroup1Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_rateGroup2Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_rateGroup3Comp { enum { WARN = 3, FATAL = 5 }; }
namespace SystemReference_saveImageBufferLogger { enum { WARN = 3, FATAL = 5 }; }
}
}
Expand Down

0 comments on commit ebc9de7

Please sign in to comment.