Merge pull request #854 from jwest115/docs/dict-spec-users-guide

User guide updates for dictionary specifier

Author: bocchino

docs/fpp-spec.html

@@ -4391,10 +4391,6 @@ <h3 id="Definitions_Dictionary-Definitions">5.16. Dictionary Definitions</h3>
 <div class="sect3">
 <h4 id="Definitions_Dictionary-Definitions_Semantics">5.16.1. Semantics</h4>
 <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
 expression appearing in <em>D</em> must have one of the following types:</p>
 </div>
@@ -4414,6 +4410,10 @@ <h4 id="Definitions_Dictionary-Definitions_Semantics">5.16.1. Semantics</h4>
 </li>
 </ul>
 </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 class="sect3">
 <h4 id="Definitions_Dictionary-Definitions_Examples">5.16.2. Examples</h4>
@@ -12037,7 +12037,7 @@ <h3 id="Analysis-and-Translation_Translation-Tools">22.4. Translation Tools</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-10-29 18:57:16 -0700
+Last updated 2025-11-02 13:05:24 -0800
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/fpp-users-guide.html

@@ -8,9 +8,6 @@ the definition in the ground dictionary.
 
 ==== 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
 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>>.
 * 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
 
 [source,fpp]

docs/spec/Definitions/Dictionary-Definitions.adoc

@@ -1051,7 +1051,8 @@ for the following:
 . None of the parameters may be a
 <<Defining-Ports_Reference-Parameters,reference parameter>>.
 
-. Each parameter must have a *displayable type*, i.e., a
+. Each parameter must have a <<Dictionary-Definitions,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>>.

docs/users-guide/Defining-Components.adoc

@@ -737,3 +737,101 @@ is not legal:
 constant
   a = 1
 --------
+
+=== Framework Constants
+
+Certain constants defined in FPP have a special meaning in the
+F Prime framework.
+These constants are called *framework constants*.
+For example, the constant `Fw.DpCfg.CONTAINER_USER_DATA_SIZE`
+defines the size of the user data field in a data product container.
+(Data products are an F Prime feature that we describe
+<<Defining-Components_Data-Products,in a later section of this manual>>.)
+You typically set these constants by overriding configuration
+files provided in the directory `default/config` in the F Prime repository.
+For example, the file `default/config/DpCfg.fpp` provides a default value for 
+`Fw.DpCfg.CONTAINER_USER_DATA_SIZE`.
+You can override this default value by providing your own version of
+the file `DpCfg.fpp`.
+The 
+https://fprime.jpl.nasa.gov/devel/docs/user-manual/framework/configuring-fprime/[F
+Prime User Manual]
+explains how to do this configuration.
+
+The FPP analyzer does not require that framework constants be defined
+unless they are used.
+For example, the following model is valid, because it neither defines nor users
+`Fw.DpCfg.CONTAINER_USER_DATA_SIZE`:
+
+[source,fpp]
+----
+constant a = 0
+----
+
+The following model is valid because it defines and uses `Fw.DpCfg.CONTAINER_USER_DATA_SIZE`:
+
+[source,fpp]
+----
+module Fw {
+
+  module DpCfg {
+
+    constant CONTAINER_USER_DATA_SIZE = 10
+
+  }
+
+}
+
+constant a = Fw.DpCfg.CONTAINER_USER_DATA_SIZE
+----
+
+The following model is invalid, because it uses `Fw.DpCfg.CONTAINER_USER_DATA_SIZE`
+without defining it:
+
+[source,fpp]
+--------
+constant a = Fw.DpCfg.CONTAINER_USER_DATA_SIZE
+--------
+
+If framework constants are defined in the FPP model, then
+then they must conform to certain rules.
+These rules are spelled out in detail in the
+https://nasa.github.io/fpp/fpp-spec.html#Definitions_Framework-Definitions_Constant-Definitions[_The
+FPP Language Specification_].
+For example, `Fw.DpCfg.CONTAINER_USER_DATA_SIZE` must have an integer type.
+So this model is invalid:
+
+[source,fpp]
+--------
+module Fw {
+
+  module DpCfg {
+
+    constant CONTAINER_USER_DATA_SIZE = "abc"
+
+  }
+
+}
+--------
+
+Here is what happens when you run this model through `fpp-check`:
+
+----
+% fpp-check
+module Fw {
+
+  module DpCfg {
+
+    constant CONTAINER_USER_DATA_SIZE = "abc"
+
+  }
+
+}
+^D
+fpp-check
+stdin:5.5
+    constant CONTAINER_USER_DATA_SIZE = "abc"
+    ^
+error: the F Prime framework constant Fw.DpCfg.CONTAINER_USER_DATA_SIZE must have an integer type
+----
+

docs/users-guide/Defining-Constants.adoc

@@ -691,3 +691,23 @@ defining `T`; elsewhere, configuration code can define
 F Prime uses this method to provide basic type whose definitions
 configure the framework.
 These types are defined in the file `config/FpConfig.fpp`.
+
+=== Framework Types
+
+Certain types defined in FPP have a special meaning in the F Prime
+framework.
+These types are called *framework types*.
+For example, the type `FwOpcodeType` defines the type of
+a command opcode.
+(Commands are an F Prime feature that we describe
+<<Defining-Components_Commands,in a later section of this manual>>.)
+
+Framework types are like <<Defining-Constants_Framework-Constants,framework 
+constants>>:
+you typically define them by overriding configuration files
+provided by F Prime, and if they are defined, then they must
+conform to certain rules.
+https://nasa.github.io/fpp/fpp-spec.html#Definitions_Framework-Definitions_Type-Definitions[_The 
+FPP Language Specification_] has all the details.
+
+

docs/users-guide/Defining-Types.adoc

@@ -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
+--------

docs/users-guide/Dictionary-Definitions.adoc

@@ -279,20 +279,62 @@ definitions>>.
 
 ==== Syntax
 
-A location specifier consists of the keyword `locate`, a kind of definition,
+In general, a location specifier consists of the keyword `locate`, a kind of 
+definition,
 the name of a definition, and a string representing a file path.
-For example, to locate the definition of constant `a` at `a.fpp`,
-we would write
+For type and constant specifiers, there is also an optional `dictionary`
+specifier, which we will describe 
+<<Specifying-Models-as-Files_Location-Specifiers_Dictionary-Definitions,below>>.
+
+For example, to locate the definition
+
+[source,fpp]
+----
+constant a = 0
+----
+
+appearing in the file `a.fpp`, we would write
 
 [source,fpp]
 ----
 # Locating a constant definition
 locate constant a at "a.fpp"
 ----
 
-For the current version of FPP, the kind of definition can be `constant`, 
-`type`, or `port`.
-To locate a type `T` in a file `T.fpp`, we would write the following:
+The kind of definition must be one of the following:
+
+[[location-specifier-kinds]]
+.Location Specifier Kinds
+|===
+|Keyword|Meaning
+
+|`component`
+|A <<Defining-Components,component definition>>
+
+|`constant`
+|A <<Defining-Constants,constant definition>>
+
+|`instance`
+|A <<Defining-Component-Instances,component instance definition>>
+
+|`interface`
+|A <<Defining-and-Using-Port-Interfaces_Defining-Port-Interfaces,port interface definition>>
+
+|`port`
+|A <<Defining-Ports,port definition>>
+
+|`state` `machine`
+|A <<Defining-State-Machines,state machine definition>>
+
+|`topology`
+|A <<Defining-Topologies,topology definition>>
+
+|`type`
+|A <<Defining-Types,type>> or <<Defining-Enums,enum>> definition
+|===
+
+As a further example, to locate a type `T` in a file `T.fpp`, we would write the 
+following:
 
 [source,fpp]
 ----
@@ -318,6 +360,8 @@ constants are then implied:
 locate type E at "E.fpp"
 ----
 
+The other kinds operate similarly.
+
 ==== Path Names
 
 As with
@@ -397,6 +441,52 @@ and suppose that file `b.fpp` contains the include specifier `include "a.fppi"`.
 When analyzing `b.fpp`, the location of the definition of the constant `a`
 is `b.fpp`, not `a.fppi`.
 
+==== Dictionary Definitions
+
+For type and constant specifiers only, if the definition being located
+is a
+<<Dictionary-Definitions,dictionary definition>>, then you must
+write the keyword `dictionary` after the keyword `locate`
+and before the definition kind.
+For example, to locate the dictionary definition
+
+[source,fpp]
+----
+dictionary constant b = 1
+----
+
+appearing in the file `b.fpp`, we would write
+
+[source,fpp]
+----
+# Locating a dictionary constant definition
+locate dictionary constant b at "b.fpp"
+----
+
+The `dictionary` keyword tells the analyzer that the definition is a dictionary
+definition and so should be included in the dependency files of the model,
+regardless of whether the definition is used in the model.
+
+If a definition is a dictionary definition and the corresponding location
+specifier does not specify `dictionary` (or vice versa), then the analyzer
+will report an error.
+
+==== Repeated Location Specifiers
+
+An FPP model may contain any number of location specifiers for the same
+definition, so long as the following conditions are met:
+
+. All the specifiers must be consistent.
+This means that all the specifiers for the same definition
+provide the same location, and either they all specify `dictionary`
+or none of them does.
+
+. All the specifiers must agree with the definition, if it exists
+in the model.
+This means that the location specifiers specify the location
+of the definition, and the specifiers specify `dictionary`
+if and only if the definition is a dictionary definition.
+
 === Locating Definitions
 
 Given a collection of FPP source files _F_, you can generate location specifiers