nasa/fpp
1
0
Fork 0
mirror of https://github.com/nasa/fpp.git synced 2025-12-10 17:29:15 -06:00
Code Issues Packages Projects Releases 83 Wiki Activity

Revise Dictionary Definitions

Browse Source
This commit is contained in:
Rob Bocchino 2025-11-02 13:21:15 -08:00
parent f3753f72f7
commit 090544f260
7 changed files with 163 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/fpp-spec.html
View File

@ -4391,10 +4391,6 @@ the definition in the ground dictionary.</p>
<div class="sect3"> <div class="sect3">
<h4 id="Definitions_Dictionary-Definitions_Semantics">5.16.1. Semantics</h4> <h4 id="Definitions_Dictionary-Definitions_Semantics">5.16.1. Semantics</h4>
<div class="paragraph"> <div class="paragraph">
<p>If a type definition <em>D</em> is a dictionary definition, then the type
defined by <em>D</em> must be a <a href="#Types_Displayable-Types">displayable type</a>.</p>
</div>
<div class="paragraph">
<p>If a constant definition <em>D</em> is a dictionary definition, then the <p>If a constant definition <em>D</em> is a dictionary definition, then the
expression appearing in <em>D</em> must have one of the following types:</p> expression appearing in <em>D</em> must have one of the following types:</p>
</div> </div>
@ -4414,6 +4410,10 @@ expression appearing in <em>D</em> must have one of the following types:</p>
</li> </li>
</ul> </ul>
</div> </div>
<div class="paragraph">
<p>If a type definition <em>D</em> is a dictionary definition, then the type
defined by <em>D</em> must be a <a href="#Types_Displayable-Types">displayable type</a>.</p>
</div>
</div> </div>
<div class="sect3"> <div class="sect3">
<h4 id="Definitions_Dictionary-Definitions_Examples">5.16.2. Examples</h4> <h4 id="Definitions_Dictionary-Definitions_Examples">5.16.2. Examples</h4>
@ -12037,7 +12037,7 @@ equivalent.</p>
</div> </div>
<div id="footer"> <div id="footer">
<div id="footer-text"> <div id="footer-text">
Last updated 2025-10-30 17:14:10 -0700 Last updated 2025-11-02 13:05:24 -0800
</div> </div>
</div> </div>
<script src="code-prettify/run_prettify.js"></script> <script src="code-prettify/run_prettify.js"></script>

142
docs/fpp-users-guide.html
View File

@ -513,12 +513,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
<li><a href="#Defining-Enums_The-Default-Value">7.5. The Default Value</a></li> <li><a href="#Defining-Enums_The-Default-Value">7.5. The Default Value</a></li>
</ul> </ul>
</li> </li>
<li><a href="#Defining-Framework-and-Dictionary-Definitions">8. Defining Framework and Dictionary Definitions</a> <li><a href="#Dictionary-Definitions">8. Dictionary Definitions</a></li>
<ul class="sectlevel2">
<li><a href="#Defining-Framework-and-Dictionary-Definitions_Framework-Definitions">8.1. Framework Definitions</a></li>
<li><a href="#Defining-Framework-and-Dictionary-Definitions_Dictionary-Definitions">8.2. Dictionary Definitions</a></li>
</ul>
</li>
<li><a href="#Defining-Ports">9. Defining Ports</a> <li><a href="#Defining-Ports">9. Defining Ports</a>
<ul class="sectlevel2"> <ul class="sectlevel2">
<li><a href="#Defining-Ports_Port-Names">9.1. Port Names</a></li> <li><a href="#Defining-Ports_Port-Names">9.1. Port Names</a></li>
@ -3298,72 +3293,99 @@ use appears inside the enum where it is defined.</p>
</div> </div>
</div> </div>
<div class="sect1"> <div class="sect1">
<h2 id="Defining-Framework-and-Dictionary-Definitions">8. Defining Framework and Dictionary Definitions</h2> <h2 id="Dictionary-Definitions">8. Dictionary Definitions</h2>
<div class="sectionbody"> <div class="sectionbody">
<div class="sect2">
<h3 id="Defining-Framework-and-Dictionary-Definitions_Framework-Definitions">8.1. Framework Definitions</h3>
<div class="paragraph"> <div class="paragraph">
<p><strong>Framework definitions</strong> are type and constant definitions that <p>One of the artifacts generated from an FPP model is a <strong>dictionary</strong>
are specially used by the F Prime Framework. If a model defines that tells the ground data system how to interpret and display
framework definitions, they must conform to the rules described the data produced by the FSW.
in the the <em>FPP Specification</em>.</p> By default, the dictionary contains representations of the following
types and constants defined in FPP:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Types and constants that are known to the framework and that are
needed by every dictionary, e.g., <code>FwOpcodeType</code>.</p>
</li>
<li>
<p>Types and constants that appear in the definitions of the data produced
by the FSW, e.g., event specifiers or telemetry specifiers.
(In later sections of this manual we will explain how to define
<a href="#Defining-Components_Events">event reports</a> and
<a href="#Defining-Components_Telemetry">telemetry channels</a>.)</p>
</li>
</ul>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>To write a framework definition, we write the type or constant <p>Sometimes you will need the dictionary to include the definition of a type or
and ensure that the definition follows the rules for that constant
framework definition.</p> that does not satisfy either of these conditions.
For example, a downlink configuration parameter may be
shared by the FSW implementation and the GDS and may be otherwise unused
in the FPP model.</p>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>For example, to write the <code>FwDpIdType</code> framework definition, <p>In this case you can mark a type or constant definition as a <strong>dictionary
we would write an alias <code>FwDpIdType</code> that represents an definition</strong>.
integer type:</p> A dictionary definition tells the FPP analyzer two things:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The definition should be included in the model, even if it
isn&#8217;t used anywhere in the model.</p>
</li>
<li>
<p>Whenever a dictionary is generated from the model, the definition should be
included in the dictionary.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>To write a dictionary definition, you write the keyword <code>dictionary</code>
before the definition.
You can do this for a constant definition, a type definition,
or an enum definition.
For example:</p>
</div> </div>
<div class="listingblock"> <div class="listingblock">
<div class="content"> <div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">type FwDpIdType = U32</code></pre> <pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = 1
dictionary array A = [3] U32
dictionary struct S { x: U32, y: F32 }
dictionary type T = S
dictionary enum E { A, B }</code></pre>
</div> </div>
</div> </div>
<div class="paragraph"> <div class="paragraph">
<p>To write the <code>Fw.DpCfg.CONTAINER_USER_DATA_SIZE</code> framework definition, <p>Each dictionary definition must observe the following rules:</p>
we would define modules <code>Fw</code> and <code>DpCfg</code> and write a constant </div>
<code>CONTAINER_USER_DATA_SIZE</code> with an integer type:</p> <div class="olist arabic">
<ol class="arabic">
<li>
<p>A dictionary constant definition must have a numeric value (integer or
floating point),
a Boolean value (true or false), a string value such as <code>"abc"</code>, or an
enumerated constant value such as <code>E.A</code>.</p>
</li>
<li>
<p>A dictionary type definition must define a <strong>displayable type</strong>, i.e., a
type that the F Prime ground data system knows how to display.
For example, the type may not be an
<a href="#Defining-Types_Abstract-Type-Definitions">abstract type</a>.
Nor may it be an array or struct type that has an abstract type
as a member type.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>For example, the following dictionary definitions are invalid:</p>
</div> </div>
<div class="listingblock"> <div class="listingblock">
<div class="content"> <div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">module Fw { <pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = { x = 1, y = 2.0 } # Error: a has struct type
module DpCfg { dictionary type T # Error: T is an abstract type</code></pre>
constant CONTAINER_USER_DATA_SIZE = 1
}
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="Defining-Framework-and-Dictionary-Definitions_Dictionary-Definitions">8.2. Dictionary Definitions</h3>
<div class="paragraph">
<p>An FPP model may include type and constant definitions
that are <strong>dictionary definitions</strong>. These definitions describe
type and constant definitions that will be output to the
dictionary.</p>
</div>
<div class="paragraph">
<p>To write a dictionary definition, prefix an array, struct,
alias, or constant definition with the <code>dictionary</code> keyword.
For example, to define a constant dictionary definition
we write the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">dictionary constant a = 1</code></pre>
</div>
</div>
<div class="paragraph">
<p>To define an array dictionary definition, we write the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">dictionary array a = [3] U32</code></pre>
</div>
</div> </div>
</div> </div>
</div> </div>
@ -12559,8 +12581,8 @@ is <code>b.fpp</code>, not <code>a.fppi</code>.</p>
<div class="sect3"> <div class="sect3">
<h4 id="Specifying-Models-as-Files_Location-Specifiers_Dictionary-Specifiers">15.4.5. Dictionary Specifiers</h4> <h4 id="Specifying-Models-as-Files_Location-Specifiers_Dictionary-Specifiers">15.4.5. Dictionary Specifiers</h4>
<div class="paragraph"> <div class="paragraph">
<p>Dictionary specifiers define the location of constant or type <p>A <strong>dictionary specifier</strong> defines the location of a
<a href="#Defining-Framework-and-Dictionary-Definitions">dictionary definitions</a>. <a href="#Dictionary-Definitions">dictionary definition</a>.
To write a dictionary specifier, write a location specifier and include To write a dictionary specifier, write a location specifier and include
the <code>dictionary</code> keyword before the <code>constant</code> or <code>type</code> keyword.</p> the <code>dictionary</code> keyword before the <code>constant</code> or <code>type</code> keyword.</p>
</div> </div>
@ -16022,7 +16044,7 @@ serialized according to its
</div> </div>
<div id="footer"> <div id="footer">
<div id="footer-text"> <div id="footer-text">
Last updated 2025-11-02 12:36:42 -0800 Last updated 2025-11-02 13:13:09 -0800
</div> </div>
</div> </div>
<script src="code-prettify/run_prettify.js"></script> <script src="code-prettify/run_prettify.js"></script>

6
docs/spec/Definitions/Dictionary-Definitions.adoc
View File

@ -8,9 +8,6 @@ the definition in the ground dictionary.
==== Semantics ==== Semantics
If a type definition _D_ is a dictionary definition, then the type
defined by _D_ must be a <<Types_Displayable-Types, displayable type>>.
If a constant definition _D_ is a dictionary definition, then the If a constant definition _D_ is a dictionary definition, then the
expression appearing in _D_ must have one of the following types: expression appearing in _D_ must have one of the following types:
@ -19,6 +16,9 @@ expression appearing in _D_ must have one of the following types:
* A <<Types_String-Types,string type>>. * A <<Types_String-Types,string type>>.
* An <<Types_Enum-Types,enum type>>. * An <<Types_Enum-Types,enum type>>.
If a type definition _D_ is a dictionary definition, then the type
defined by _D_ must be a <<Types_Displayable-Types, displayable type>>.
==== Examples ==== Examples
[source,fpp] [source,fpp]

56
docs/users-guide/Defining-Framework-and-Dictionary-Definitions.adoc
View File

@ -1,56 +0,0 @@
== Defining Framework and Dictionary Definitions
=== Framework Definitions
*Framework definitions* are type and constant definitions that
are specially used by the F Prime Framework. If a model defines
framework definitions, they must conform to the rules described
in the the _FPP Specification_.
To write a framework definition, we write the type or constant
and ensure that the definition follows the rules for that
framework definition.
For example, to write the `FwDpIdType` framework definition,
we would write an alias `FwDpIdType` that represents an
integer type:
[source,fpp]
----
type FwDpIdType = U32
----
To write the `Fw.DpCfg.CONTAINER_USER_DATA_SIZE` framework definition,
we would define modules `Fw` and `DpCfg` and write a constant
`CONTAINER_USER_DATA_SIZE` with an integer type:
[source,fpp]
----
module Fw {
module DpCfg {
constant CONTAINER_USER_DATA_SIZE = 1
}
}
----
=== Dictionary Definitions
An FPP model may include type and constant definitions
that are *dictionary definitions*. These definitions describe
type and constant definitions that will be output to the
dictionary.
To write a dictionary definition, prefix an array, struct,
alias, or constant definition with the `dictionary` keyword.
For example, to define a constant dictionary definition
we write the following:
[source,fpp]
----
dictionary constant a = 1
----
To define an array dictionary definition, we write the following:
[source,fpp]
----
dictionary array a = [3] U32
----

70
docs/users-guide/Dictionary-Definitions.adoc Normal file
View File

@ -0,0 +1,70 @@
== Dictionary Definitions
One of the artifacts generated from an FPP model is a *dictionary*
that tells the ground data system how to interpret and display
the data produced by the FSW.
By default, the dictionary contains representations of the following
types and constants defined in FPP:
* Types and constants that are known to the framework and that are
needed by every dictionary, e.g., `FwOpcodeType`.
* Types and constants that appear in the definitions of the data produced
by the FSW, e.g., event specifiers or telemetry specifiers.
(In later sections of this manual we will explain how to define
<<Defining-Components_Events,event reports>> and
<<Defining-Components_Telemetry,telemetry channels>>.)
Sometimes you will need the dictionary to include the definition of a type or
constant
that does not satisfy either of these conditions.
For example, a downlink configuration parameter may be
shared by the FSW implementation and the GDS and may be otherwise unused
in the FPP model.
In this case you can mark a type or constant definition as a *dictionary
definition*.
A dictionary definition tells the FPP analyzer two things:
. The definition should be included in the model, even if it
isn't used anywhere in the model.
. Whenever a dictionary is generated from the model, the definition should be
included in the dictionary.
To write a dictionary definition, you write the keyword `dictionary`
before the definition.
You can do this for a constant definition, a type definition,
or an enum definition.
For example:
[source,fpp]
----
dictionary constant a = 1
dictionary array A = [3] U32
dictionary struct S { x: U32, y: F32 }
dictionary type T = S
dictionary enum E { A, B }
----
Each dictionary definition must observe the following rules:
. A dictionary constant definition must have a numeric value (integer or
floating point),
a Boolean value (true or false), a string value such as `"abc"`, or an
enumerated constant value such as `E.A`.
. A dictionary type definition must define a *displayable type*, i.e., a
type that the F Prime ground data system knows how to display.
For example, the type may not be an
<<Defining-Types_Abstract-Type-Definitions,abstract type>>.
Nor may it be an array or struct type that has an abstract type
as a member type.
For example, the following dictionary definitions are invalid:
[source,fpp]
--------
dictionary constant a = { x = 1, y = 2.0 } # Error: a has struct type
dictionary type T # Error: T is an abstract type
--------

4
docs/users-guide/Specifying-Models-as-Files.adoc
View File

@ -399,8 +399,8 @@ is `b.fpp`, not `a.fppi`.
==== Dictionary Specifiers ==== Dictionary Specifiers
Dictionary specifiers define the location of constant or type A *dictionary specifier* defines the location of a
<<Defining-Framework-and-Dictionary-Definitions,dictionary definitions>>. <<Dictionary-Definitions,dictionary definition>>.
To write a dictionary specifier, write a location specifier and include To write a dictionary specifier, write a location specifier and include
the `dictionary` keyword before the `constant` or `type` keyword. the `dictionary` keyword before the `constant` or `type` keyword.

2
docs/users-guide/defs.sh
View File

@ -17,7 +17,7 @@ Writing-Comments-and-Annotations.adoc
Defining-Modules.adoc Defining-Modules.adoc
Defining-Types.adoc Defining-Types.adoc
Defining-Enums.adoc Defining-Enums.adoc
Defining-Framework-and-Dictionary-Definitions.adoc Dictionary-Definitions.adoc
Defining-Ports.adoc Defining-Ports.adoc
Defining-State-Machines.adoc Defining-State-Machines.adoc
Defining-Components.adoc Defining-Components.adoc