type identifier = type-name
[
+dictionary
+]
+type identifier = type-name
= symbol.
Elsewhere in the model, the name N may be used as alias of (i.e., an
alternate name for) the type T.
If the optional keyword dictionary is present, then the
+definition must conform to the rules stated in the
+dictionary definitions section.
array identifier =
+
[
+dictionary
+]
+array identifier =
[ expression ] type-name
[
default expression
@@ -1779,6 +1797,11 @@ The type of the expression must be
When displaying the array, the format is applied to each element of the array.
There is one argument to the format string, which is an array member.
If the optional keyword dictionary is present, then the
+definition must conform to the rules stated in the
+dictionary definitions section.
constant
+
[
+dictionary
+]
+constant
identifier
=
expression
If the optional keyword dictionary is present, then the
+definition must conform to the rules stated in the
+dictionary definitions section.
enum identifier
+
[
+dictionary
+]
+enum identifier
[ : type-name ]
{ enum-constant-sequence }
[
@@ -2605,6 +2639,11 @@ If present, it specifies the default value a
with the enum definition.
The type of the expression must be the type of the enum definition.
If the optional keyword dictionary is present, then the
+definition must conform to the rules stated in the
+dictionary definitions section.
struct identifier
+
[
+dictionary
+]
+struct identifier
{ struct-type-member-sequence }
[ default expression ]
If the optional keyword dictionary is present, then the
+definition must conform to the rules stated in the
+dictionary definitions section.
If the optional keyword dictionary appears in a type definition or
+a constant definition, then that definition is called a
+dictionary definition.
+A dictionary definition instructs the code generator to include
+the definition in the ground dictionary.
If a constant definition D is a dictionary definition, then the +expression appearing in D must have one of the following types:
+A numeric type.
+The Boolean type.
+A string type.
+An enum type.
+If a type definition D is a dictionary definition, then the type +defined by D must be a displayable type.
+dictionary type T = U32
+dictionary array A = [3] string
+dictionary constant a = 0
+
+enum E { X, Y }
+dictionary constant b = E.X
+
+type T1
+dictionary type T2 = T1 # Error: T2 is not displayable
+
+dictionary constant c = { x = U32 } # Error: struct type is not allowedA constant location specifier locate constant
+
A constant location specifier locate
+[
+dictionary
+]
+constant
+qual-ident at
+string-literal
A port interface specifier locate
+interface
qual-ident at
string-literal
A type location specifier locate type
+
A type location specifier locate
+[
+dictionary
+]
+type
qual-ident at
string-literal
If the optional keyword dictionary appears in a location specifier S,
+then S is called a dictionary specifier.
A location specifier S with qualified identifier Q must conform +to the following rules:
+The qualified identifier Q is resolved like a +
Q is resolved like a use that refers to a definition as follows:
A component instance location specifier refers to a +component instance definition.
+A component location specifier refers to a +component definition.
+A constant location specifier refers to a constant definition.
A port interface location specifier refers to a +port interface definition.
+A port location specifier refers to a +port definition.
+A state machine location specifier refers to a +state machine definition.
+A topology location specifier refers to a +topology definition.
+A type location specifier refers to an array definition, enum definition, struct definition, or abstract type definition.
A port location specifier refers to a -port definition.
-A component location specifier refers to a -component definition.
-A component instance location specifier refers to a -component instance definition.
-A topology location specifier refers to a -topology definition.
-A state machine location specifier refers to a -state machine definition.
-Q need not actually refer to any definition. This rule allows the specification of dependencies for a larger set of files than the ones involved in a particular analysis -or translation.
+or translation. +If Q does refer to a definition D, then S +must be a dictionary specifier if D is a +dictionary definition; +otherwise it must not be.The string literal must specify the path of an FPP source file, relative to the @@ -6674,8 +6808,19 @@ location specifier.
Multiple location specifiers for the same definition are allowed in a single -model, so long as the locations are all -consistent.
+model, so long as the following +conditions are met: +All of the specifiers must be dictionary specifiers, or none of them must +be.
+All the specifiers must have the same locations.
+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
+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
+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:
constant a = 0The following model is valid because it defines and uses Fw.DpCfg.CONTAINER_USER_DATA_SIZE:
module Fw {
+
+ module DpCfg {
+
+ constant CONTAINER_USER_DATA_SIZE = 10
+
+ }
+
+}
+
+constant a = Fw.DpCfg.CONTAINER_USER_DATA_SIZEThe following model is invalid, because it uses Fw.DpCfg.CONTAINER_USER_DATA_SIZE
+without defining it:
constant a = Fw.DpCfg.CONTAINER_USER_DATA_SIZEIf 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
+The
+FPP Language Specification.
+For example, Fw.DpCfg.CONTAINER_USER_DATA_SIZE must have an integer type.
+So this model is invalid:
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
+config/FpConfig.fpp.
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
+in a later section of this manual.)
Framework types are like 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. +The +FPP Language Specification has all the details.
+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 +event reports and +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 that +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:
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 +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:
+dictionary constant a = { x = 1, y = 2.0 } # Error: a has struct type
+dictionary type T # Error: T is an abstract typeA port definition defines an F Prime port. @@ -3177,7 +3396,7 @@ carried on the port, and (3) an optional return type.
The simplest port definition consists of the keyword port followed
by a name.
@@ -3195,7 +3414,7 @@ This kind of port can be useful for sending or receiving a triggering event.
More often, a port will carry data. To specify the data, you write formal parameters @@ -3246,7 +3465,7 @@ port P(
As discussed further in the sections on defining components @@ -3432,7 +3651,7 @@ consisting of the first 40 characters of the original string.
You may write the keyword ref in front of any formal parameter p
of a port definition.
@@ -3491,7 +3710,7 @@ We discuss this pattern in the section on
Optionally, you can give a port definition a return type.
To do this you write an arrow -> and a type
@@ -3612,7 +3831,7 @@ port P(ref result: U32) -> Status
Whenever a C++ formal parameter p enables sharing of data between
an invoking component and a handler function pIn_handler,
@@ -3679,7 +3898,7 @@ reference and transfer ownership from A to B and vice
A port definition is an annotatable element. @@ -3701,7 +3920,7 @@ port P(
A hierarchical state machine (state machine for short) @@ -3766,7 +3985,7 @@ The component also provides the functions that are called when the state machine does actions and evaluates guards.
External state machines: To define an external state machine, you write the keywords @@ -3815,7 +4034,7 @@ Prime design documentation.
In this and the following sections, we explain how to define internal state machines, i.e., state machines that are fully @@ -4017,7 +4236,7 @@ state machine Device {
An action is a function that a state machine calls at a specified point in its behavior. @@ -4028,7 +4247,7 @@ When a state machine instance calls the function associated with an action A, we say that it does A.
To define an action, you write the keyword action followed
by the name of the action.
@@ -4134,7 +4353,7 @@ terminating punctuation.
In addition to doing actions on transitions, a state machine can do actions on entry to or exit from a state. @@ -4253,7 +4472,7 @@ exit specifier.
Optionally, signals and actions may carry data values. To specify that a signal or action carries a data value, @@ -4362,7 +4581,7 @@ In this case the value is ignored when doing the action.
When an FPP state machine receives a signal, the handling of that signal is atomic. @@ -4404,14 +4623,14 @@ Prime design documentation.
In this section, we provide more details on how to write state transitions in FPP state machines.
Sometimes it is useful to specify that a transition should occur only if a certain condition is true. @@ -4537,7 +4756,7 @@ it passes in the value as an argument to the function.
When a state transition has the same state S as its source
and its target, and S has no substates, we call the transition
@@ -4654,7 +4873,7 @@ it receives a cmdReset signal, the following behavior occurs:
An internal transition is like a self transition, @@ -4751,7 +4970,7 @@ carry data of a compatible type.
A choice definition is a state machine member that
defines a branch point for one or more transitions.
@@ -5050,7 +5269,7 @@ go to C3, and C3 to go to C1.
As with UML state machines, FPP state machines can have hierarchy. That is, we can do the following:
@@ -5096,7 +5315,7 @@ In the following subsections, we explain how to define hierarchical state machines in FPP.In this section we explain how to define and use substates.
In general, when a transition T is defined in a parent state S, T behaves as if it were defined in each of the @@ -5493,7 +5712,7 @@ by behavioral polymorphism.
In previous sections on entry and exit actions and on @@ -5539,10 +5758,10 @@ order of the traversal, do the entry actions of S', if any.
For example, suppose that M has a state A with substates B and C, B has substate D, and C has substate E. -Suppose that T goes from C to E. +Suppose that T goes from D to E. Then least common ancestor is A, and the following actions would be done, in the following order: -the exit actions of C, the exit actions of B, +the exit actions of D, the exit actions of B, the actions of T, the entry actions of C, and the entry actions of E.
Let S1 and S2 be states. If S1 is equal to S2, or S1 is an ancestor of S2, or S2 @@ -5716,7 +5935,7 @@ be overridden.
Like state definitions, choice definitions are hierarchical. That is, you may define a choice inside a state. @@ -5834,7 +6053,7 @@ entry actions of B'.
In F Prime, the component is the basic unit of FSW function. @@ -5857,7 +6076,7 @@ A passive component has no thread of control and no message queue; it is like a non-threaded function library.
An FPP component definition defines an F Prime component. To write a component definition, you write the following:
@@ -5904,7 +6123,7 @@ except for importing port interfaces, which we describe inA port instance is a component member that specifies an instance of an FPP port used by the instances of the component. @@ -5920,7 +6139,7 @@ as the name of the instance and the direction of invocation (input or output).
The simplest port instance specifies a kind, a name, and a type. The kind is one of the following:
@@ -6029,7 +6248,7 @@ of typeF32Value.
The port instances appearing in a component definition must satisfy certain rules. @@ -6112,7 +6331,7 @@ active component Error {
When you specify a port instance as part of an FPP component, you are actually specifying an array of port instances. @@ -6157,7 +6376,7 @@ passive component F32Adder {
For async input ports, you may specify a priority.
The priority specification is not allowed for other kinds of ports.
@@ -6197,7 +6416,7 @@ from the message queue.
By default, if an invocation of an async input port causes
a message queue to overflow, then a FSW assertion fails.
@@ -6265,7 +6484,7 @@ for async input ports.
When writing a port instance, instead of specifying a named port type,
you may write the keyword serial.
@@ -6312,7 +6531,7 @@ the F Prime User M
A special port instance is a port instance that has a special behavior in F Prime. @@ -6328,7 +6547,7 @@ commands, events, telemetry, parameters, time, and data products.
A command is an instruction to the spacecraft to perform an action. Each component instance C that specifies commands has the following @@ -6450,7 +6669,7 @@ response, and implementing command handlers, see the
An event is a report that something happened, for example, that a file was successfully uplinked. @@ -6531,7 +6750,7 @@ simplified definitions of these ports:
Telemetry is data regarding the state of the system. A telemetry port allows a component to emit telemetry. @@ -6580,7 +6799,7 @@ simplified definition of this port:
A parameter is a configurable constant that may be updated from the ground. @@ -6665,7 +6884,7 @@ simplified definitions of these ports:
A time get port allows a component to get the system time from a time component. @@ -6715,7 +6934,7 @@ simplified definition of this port:
A data product is a collection of data that can be stored to an onboard file system, given a priority, and downlinked in priority @@ -6840,7 +7059,7 @@ Prime design documentation.
An internal port is a port that a component can use to send a message to itself. @@ -6966,7 +7185,7 @@ Try it and see.
When defining an F Prime component, you may specify one or more commands. When you are operating the FSW, you use the F Prime Ground Data System @@ -6983,7 +7202,7 @@ handling, see the Here we concentrate on how to specify commands in FPP.
The simplest command consists of a kind followed by the keyword
command and a name.
@@ -7081,7 +7300,7 @@ running the result through fpp-check.
When specifying a command, you may specify one or more formal parameters. @@ -7102,7 +7321,8 @@ for the following:
reference parameter.Each parameter must have a displayable type, i.e., a +
Each parameter must have 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 abstract type. @@ -7167,7 +7387,7 @@ stubs for the special command ports that are required by
Every command in an F Prime FSW application has an opcode. The opcode is a number that uniquely identifies the command. @@ -7277,7 +7497,7 @@ active component DuplicateOpcode {
When specifying an async command, you may specify
priority and
@@ -7331,7 +7551,7 @@ to sync and see what fpp-check has to say about it.
When defining an F Prime component, you may specify one or more events. The F Prime framework converts each event into a C++ @@ -7346,7 +7566,7 @@ handling, see the Here we concentrate on how to specify events in FPP.
The simplest event consists of the keyword event, a name, a severity,
and a format string.
@@ -7434,7 +7654,7 @@ code above and running the result through fpp-check.
When specifying an event, you may specify one or more formal parameters. @@ -7511,7 +7731,7 @@ passive component EventParameters {
Every event in an F Prime FSW application has a unique numeric identifier. @@ -7582,7 +7802,7 @@ passive component EventIdentifiers {
Sometimes it is necessary to throttle events, to ensure that they do not flood the system. @@ -7701,7 +7921,7 @@ emit the event until the throttle is cleared through FSW command. For details, s
When defining an F Prime component, you may specify one or more telemetry channels. @@ -7721,7 +7941,7 @@ handling, see the Here we concentrate on how to specify telemetry channels in FPP.
The simplest telemetry channel consists of the keyword telemetry,
a name, and a data type.
@@ -7778,7 +7998,7 @@ Both ports are required for any component that has telemetry.
Every telemetry channel in an F Prime FSW application has a unique numeric identifier. @@ -7843,7 +8063,7 @@ passive component TlmIdentifiers {
You can specify how often the telemetry is emitted on a channel C. There are two possibilities:
@@ -7924,7 +8144,7 @@ passive component TlmUpdate {You may specify how a telemetry channel is formatted in the ground display. @@ -7976,7 +8196,7 @@ passive component TlmFormat {
You may specify limits, or bounds, on the expected values carried on a telemetry channel. @@ -8063,7 +8283,7 @@ condition (2).
When defining an F Prime component, you may specify one or more parameters. @@ -8081,7 +8301,7 @@ For complete information about F Prime parameters, see the Here we concentrate on how to specify parameters in FPP.
The simplest parameter consists of the keyword param,
a name, and a data type.
@@ -8158,7 +8378,7 @@ above and see what fpp-check does.
You can specify a default value for any parameter. This is the value that F Prime will use if no value is @@ -8219,7 +8439,7 @@ passive component ParamDefaults {
Every parameter in an F Prime FSW application has a unique numeric identifier. @@ -8295,7 +8515,7 @@ passive component ParamIdentifiers {
Each parameter that you specify has two implied commands: one for setting the value bound to the parameter locally in the @@ -8396,7 +8616,7 @@ passive component ParamOpcodes {
In the default case, when you specify a parameter P in a component C, the FPP code generator produces code for storing @@ -8465,7 +8685,7 @@ Prime User Manual explains how to do this.
When defining an F Prime component, you may specify the data products produced by that component. @@ -8480,7 +8700,7 @@ For more information about these F Prime features, see the Prime User Manual.
In F Prime, a data product is represented as a container. One container holds one data product, and each data product @@ -8585,7 +8805,7 @@ specifier, and vice versa.
Every record in an F Prime FSW application has a unique numeric identifier. @@ -8666,7 +8886,7 @@ and the container identifiers must be unique.
In the basic form of a record described above, each record that does not have @@ -8733,7 +8953,7 @@ it is provided when the record is serialized into a container.
A state machine instance is a component member that instantiates an FPP state machine. @@ -8804,7 +9024,7 @@ Prime design documentation.
You can write a constant definition, type definition, @@ -8943,7 +9163,7 @@ We will have more to say about this issue in the section on
Component definitions can become long, especially when there are many commands, events, telemetry channels, and parameters. @@ -8996,7 +9216,7 @@ We discuss include specifiers further in the section on
Some F Prime components employ the following pattern:
A common pattern in F Prime is to use an identical set of @@ -9104,7 +9324,7 @@ FPP has special support for defining and using port interfaces, which we describe in this section.
A port interface definition defines a port interface. To write a port interface definition, you write the following:
@@ -9181,7 +9401,7 @@ is used in a component, as described in the next section.Once you have defined a port interface, you can use it in a component definition. To do this you write a component @@ -9252,7 +9472,7 @@ passive component C {
You can import a port interface into another interface. For example:
@@ -9291,7 +9511,7 @@ interface I2 {As discussed in the section on defining-components, @@ -9303,14 +9523,14 @@ In the next section, we will explain how to construct topologies.
To instantiate a component, you write a component instance definition. The form of a component instance definition depends on the kind of the component you are instantiating: passive, queued, or active.
To instantiate a passive component, you write the following:
leftEngineTemp, which goes from
Instantiating a queued component is just like instantiating a passive component, except that you must also specify @@ -9522,7 +9742,7 @@ In the component instance definition, we have specified a queue size of 10.
Instantiating an active component is like instantiating a queued component, except that you may specify additional parameters @@ -9648,7 +9868,7 @@ associated with the instance should run on CPU 0.
When you define a component instance I, the FPP translator needs to know the following information about the C++ implementation of I:
@@ -9782,7 +10002,7 @@ file../../Svc/LinuxTime/LinuxTime.hpp.
In an F Prime FSW application, each component instance I has some associated C++ code @@ -9813,7 +10033,7 @@ However, most of the code is in fact initialization code, and so FPP uses "init" as a shorthand name.)
The FPP translator uses init specifiers when it generates code for an F Prime topology. @@ -10028,7 +10248,7 @@ instance needs to deallocate memory or release resources on program exit.
You may write one or more init specifiers as part of a component
instance definition.
@@ -10167,7 +10387,7 @@ use the state value that we just mentioned.
FPP uses the following rules to generate the names associated with component instances. @@ -10230,7 +10450,7 @@ according to the previous paragraph.
In F Prime, a topology or connection graph is the @@ -10251,7 +10471,7 @@ C++ code. In this section we explain how to define a topology in FPP.
We begin with a simple example that shows how many of the pieces fit together.
@@ -10381,7 +10601,7 @@ terminating punctuation is a semicolon.In general, an FPP topology consists of a list of instances and a set of named connection graphs. @@ -10389,7 +10609,7 @@ There are two ways to specify connection graphs: direct graph specifiers and pattern graph specifiers.
A direct graph specifier provides a name and a list of connections. @@ -10510,7 +10730,7 @@ then the port type of P may not specify a
A few connection patterns are so common in F Prime that they get special treatment in FPP. @@ -10832,7 +11052,7 @@ each on its own line, or you can separate them with commas:
As discussed in the section on defining components, @@ -10845,7 +11065,7 @@ In FPP, there are three ways to specify port numbers: explicit numbering, matched numbering, and general numbering.
To use explicit numbering, you provide an explicit port number for a connection endpoint. @@ -10992,7 +11212,7 @@ For example, this is what we did in the section on
Automatic matching: After resolving @@ -11185,7 +11405,7 @@ and use that twice to do the matching by hand.
After resolving explicit numbering and @@ -11240,7 +11460,7 @@ a.p[1] -> c.p[0]
It is often useful to decompose a flight software project into several topologies. @@ -11276,7 +11496,7 @@ one topology into another one. In this section of the User Guide, we explain how to do that.
To import a topology A into a topology B, you write
import A inside topology B, like this:
B.
Often when importing topology A into topology B, you
want to include one or more instances in A that exist just
@@ -11460,7 +11680,7 @@ the connection is imported into B.
Multiple imports are allowed. For example:
@@ -11498,7 +11718,7 @@ For example, this is incorrect:In general, transitive imports are allowed.
For example, topology A may import topology B,
@@ -11515,7 +11735,7 @@ and C imports A, you will get an error.
You can include code from another file in a topology definition. You do this by writing an include specifier. @@ -11539,7 +11759,7 @@ below.
When defining a topology, you may (but are not required to) specify how the telemetry channels @@ -11552,7 +11772,7 @@ individual channels. In this section we explain how to specify telemetry packets in FPP.
To group the channels of a topology T into packets, you write a
telemetry packet set as part of the definition of T.
@@ -11707,7 +11927,7 @@ channel M.c1.T instead of channel c1.T.
Within a telemetry packet set, every packet has a unique numeric identifier. Typically the identifiers start at zero and count up by one. @@ -11743,7 +11963,7 @@ packet P2 id 1 group 1 {
By default, every telemetry channel in the topology must appear in at least one telemetry packet. @@ -11808,7 +12028,7 @@ packet and also to appear in the omitted list.
You may specify more than one telemetry packet set in a topology. Each telemetry packet set must have a distinct name. @@ -11867,7 +12087,7 @@ telemetry packet set to use to decode the packets.
When writing a telemetry packet set, you can include code @@ -11913,7 +12133,7 @@ from other files, if you wish.
The previous sections have explained the syntactic and semantic elements @@ -11932,7 +12152,7 @@ For more comprehensive coverage, see the FPP wiki.
FPP does not require any particular division of model elements into files. @@ -12008,7 +12228,7 @@ multiple blocks
As part of an FPP model, you can write one or more include specifiers. An include specifier is an instruction to include FPP source elements @@ -12159,7 +12379,7 @@ error: identifier expected
Whenever a model spans two or more files, one file F may use one or more definitions appearing in other files. @@ -12256,7 +12476,7 @@ the CMake build process included in the F Prime distribution.
A location specifier is a unit of syntax in an FPP model. It specifies the location of a definition used in the model.
@@ -12270,12 +12490,25 @@ in the section on loc definitions.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
dictionary
+specifier, which we will describe
+below.
+For example, to locate the definition
+constant a = 0appearing in the file a.fpp, we would write
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:
+| Keyword | +Meaning | +
|---|---|
|
++ |
|
++ |
|
++ |
|
++ |
|
++ |
|
++ |
|
++ |
|
++ |
As a further example, to locate a type T in a file T.fpp, we would write the
+following:
The other kinds operate similarly.
+As with
include specifiers,
@@ -12345,7 +12630,7 @@ Then in b.fpp we could write this:
The definition name appearing after the keyword locate
may be a qualified name.
@@ -12392,7 +12677,7 @@ definitions and their uses.
When you write a file that contains definitions and you
include that file in another file,
@@ -12405,9 +12690,68 @@ When analyzing b.fpp, the location of the definition of the constan
is b.fpp, not a.fppi.
For type and constant specifiers only, if the definition being located
+is a
+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
dictionary constant b = 1appearing in the file b.fpp, we would write
# 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.
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.
Given a collection of FPP source files F, you can generate location specifiers
for all the definitions in F.
@@ -12419,7 +12763,7 @@ When analyzing other files that use the constants, you can use the location
specifiers to discover dependencies on individual files within Constants.
To locate definitions, do the following:
By default, the location path is relative to the current directory. @@ -12478,7 +12822,7 @@ For example, running
Consider the case where you write a definition in one file and
include that file in another file via an
@@ -12534,7 +12878,7 @@ If your main FPP files end with .fpp and your included FPP files en
Given files F and location specifiers L that locate the definitions used in
F, you can
@@ -12542,7 +12886,7 @@ generate the dependencies of F.
The tool for doing this is called fpp-depend.
To run fpp-depend, you pass it as input (1) files F that you want to
analyze
@@ -12614,7 +12958,7 @@ So the following is equivalent:
fpp-depend computes dependencies transitively.
This means that if A depends on B and B
@@ -12673,7 +13017,7 @@ produces both dependencies:
Suppose we construct the files locations.fpp and a.fpp, b.fpp, and c.fpp
as described in the previous section, but then we temporarily remove b.fpp.
@@ -12736,7 +13080,7 @@ the dependency [path-prefix]/b.fpp to standard output.
Suppose file a.fpp contains the
include specifier
@@ -12802,7 +13146,7 @@ to the output plus the contents of file.
As discussed
above, the standard output of fpp-depend reports transitive dependencies.
@@ -12896,7 +13240,7 @@ included files are already present in direct.txt.
Certain FPP constructs imply dependencies on parts of the F Prime framework that may not be available on all platforms. @@ -12932,7 +13276,7 @@ be provided to the linker.
Given a collection of files F and their dependencies D, you can generate the locations of the definitions appearing in D and used in F. @@ -13012,7 +13356,7 @@ for the location specifiers.
Because FPP associates locations with symbols, and the locations are path names, care is required when using path names that are @@ -13021,7 +13365,7 @@ There are two issues to consider: relative paths and unique locations.
A relative path is a path that does not start with a slash and is relative to the current directory path, which is @@ -13087,7 +13431,7 @@ See that section for details, and for suggested workarounds.
The FPP analyzers assume that each symbol s has a unique path defining the location of the source file where @@ -13111,7 +13455,7 @@ time, after resolving relative paths as described above.
The previous section explained how to specify an FPP model @@ -13123,7 +13467,7 @@ translation on part or all of an FPP model, after specifying the model and computing its dependencies.
It is often useful to check a model for correctness, without
doing any translation.
@@ -13293,7 +13637,7 @@ even though c.Out has two ports and only one of them is connected.<
This section describes how to generate C++ from FPP.
fpp-check<
translated to C++ files.