The F Prime Prime (FPP) User’s Guide, Unreleased, after v2.2.1

Certain sequences of letters such as constant are called out as reserved words (also called keywords) in FPP. Each reserved word has a special meaning, such as introducing a constant declaration. The FPP Language Specification has a complete list of reserved words. In this document, we will introduce reserved words as needed to explain the language features.

Using a reserved word as a name in the ordinary way causes a parsing error. For example, this code is incorrect:

To use a reserved word as a name, you must put the character $ in front of it with no space. For example, this code is legal:

The character sequence $constant represents the name constant, as opposed to the keyword constant.

You can put the character $ in front of any identifier, not just a keyword. If the identifier is not a keyword, then the $ has no effect. For example, $name has the same meaning as name.

FPP will not let you define two different symbols of the same kind with the same name. For example, this code will produce an error:

Two symbols can have the same unqualified name if they reside in different modules or enums; these concepts are explained below. Two symbols can also have the same name if the analyzer can distinguish them based on their kinds. For example, an array type (described below) and a constant can have the same name, but an array type and a struct type may not. The FPP Language Specification has all the details.

A primitive value expression represents a primitive machine value, such as an integer. It is one of the following:

As an exercise, construct some constant definitions with primitive values as their expressions, and feed the results to fpp-check. For example:

If you get an error, make sure you understand why.

A string value represents a string of characters. There are two kinds of string values: single-line strings and multiline strings.

Single-line strings: A single-line string represents a string of characters that does not contain a newline character. It is written as a string of characters enclosed in double quotation marks ". For example:

To put the double-quote character in a string, write the double quote character as \", like this:

To encode the character \ followed by the character ", write the backslash character as \\, like this:

This string represents the literal character sequence \, ".

In general, the sequence \ followed by a character c is translated to c. This sequence is called an escape sequence.

Multiline strings: A multiline string represents a string of characters that may contain a newline character. It is enclosed in a pair of sequences of three double quotation marks """. For example:

When interpreting a multiline string, FPP ignores any newline characters at the start and end of the string. FPP also ignores any blanks to the left of the column where the first """ appears. For example, the string shown above consists of three lines and starts with This.

Literal quotation marks are allowed inside a multiline string:

Escape sequences work as for single-line strings. For example:

An array value expression represents a fixed-size array of values. To write an array value expression, you write a comma-separated list of one or more values (the array elements) enclosed in square brackets. Here is an example:

This code associates the name a with the array of integers [ 1, 2, 3 ].

As mentioned in the introduction, an FPP model describes the structure of a FSW application; the computations are specified in a target language such as C++. As a result, FPP does not provide an array indexing operation. In particular, it does not specify the index of the leftmost array element; that is up to the target language. For example, if the target language is C++, then array indices start at zero.

Here are some rules for writing array values:

What does it mean for types to match? The FPP Specification has all the details, and we won’t attempt to repeat them here. In general, things work as you would expect: for example, we can convert an integer value to a floating-point value, so the following code is allowed:

It evaluates to an array of two floating-point values.

If you are not sure whether a type conversion is allowed, you can ask fpp-check. For example: can we convert a Boolean value to an integer value? In older languages like C and C++ we can, but in many newer languages we can’t. Here is the answer in FPP:

So no, we can’t.

Here are two more points about array values:

A struct value expression represents a C- or C++-style structure, i.e., a mapping of names to values. To write a struct value expression, you write a comma-separated list of zero or more struct members enclosed in curly braces. A struct member consists of a name, an equals sign, and a value.

Here is an example:

This code associates the name s with a struct value. The struct value has two members x and y. Member x has the integer value 1, and member y has the string value "abc".

The order of members: When writing a struct value, the order in which the members appear does not matter. For example, in the following code, constants s1 and s2 denote the same value:

The empty struct: The empty struct is allowed:

Arrays in structs: You can write an array value as a member of a struct value. For example, this code is allowed:

Structs in arrays: You can write a struct value as a member of an array value. For example, this code is allowed:

This code is not allowed, because the element types don’t match — an array is not compatible with a struct.

However, this code is allowed:

Notice that the first member of a is a struct with two members x and y. The second member of a is also a struct, but it has only one member x. When the FPP analyzer detects that a struct type is missing a member, it automatically adds the member, giving it a default value. The default values are the ones you would expect: zero for numeric members, the empty string for string members, and false for Boolean members. So the code above is equivalent to the following:

A name expression is a use of a name appearing in a constant definition. It stands for the associated constant value. For example:

In this code, constant b has the value 1.

The order of definitions does not matter, so this code is equivalent:

The only requirement is that there may not be any cycles in the graph consisting of constant definitions and their uses. For example, this code is illegal, because there is a cycle from a to b to c and back to a:

Try submitting this code to fpp-check, to see what happens.

Names like a, b, and c are simple or unqualified names. Names can also be qualified: for example A.a is allowed. We will discuss qualified names further when we introduce module definitions and enum definitions below.

A value arithmetic expression performs arithmetic on values. It is one of the following:

The following rules apply to arithmetic expressions:

Wherever you can write a value inside an expression, you can write a more complex expression there, so long as the types work out. For example, these expressions are valid:

The first example is a binary expression whose first operand is a parentheses expression; that parentheses expression in turn has a binary expression as its subexpression. The second example is an array expression whose first element is a binary expression.

This expression is invalid, because 1 + 2.0 evaluates to a floating-point value, which is incompatible with type string:

Compound expressions are evaluated in the obvious way. For example, the constant definitions above are equivalent to the following:

For compound arithmetic expressions, the precedence and associativity rules are the usual ones (evaluate parentheses first, then multiplication, and so forth).

As an example, here is an array type definition that associates the name A with an array of three values, each of which is a 32-bit unsigned integer:

In general, to write an array type definition, you write the following:

Notice that the size expression precedes the element type, and the whole type reads left to right. For example, you may read the type [3] U32 as "array of 3 U32."

The size may be any legal expression. It doesn’t have to be a literal integer. For example:

As for array values, an array type must have size greater than zero and less than or equal to 256.

The following type names are available for the element types:

An array type definition may not refer to itself (array type definitions are not recursive). For example, this definition is illegal:

Optionally, you can specify a default value for an array type. To do this, you write the keyword default and an expression that evaluates to an array value. For example, here is an array type A with default value [ 1, 2, 3 ]:

A default value expression need not be a literal array value; it can be any expression with the correct type. For example, you can create a named constant with an array value and use it multiple times, like this:

If you don’t specify a default value, then the type gets an automatic default value, consisting of the default value for each element. The default numeric value is zero, the default Boolean value is false, the default string value is "", and the default value of an array type is specified in the type definition.

The type of the default expression must match the size and element type of the array, with type conversions allowed as discussed for array values. For example, this default expression is allowed, because we can convert integer values to floating-point values, and we can promote a single value to an array of three values:

However, these default expressions are not allowed:

You can specify an optional format string which says how to display each element value and optionally provides some surrounding text. For example, here is an array definition that interprets three integer values as wheel speeds measured in RPMs:

Then an element with value 100 would have the format 100 RPM.

Note that the format string specifies the format for an element, not the entire array. The way an entire array is displayed is implementation-specific. A standard way is a comma-separated list enclosed in square brackets. For example, a value [ 100, 200, 300 ] of type WheelSpeeds might be displayed as [ 100 RPM, 200 RPM, 300 RPM ]. Or, since the format is the same for all elements, the implementation could display the array as [ 100, 200, 300 ] RPM.

The special character sequence {} is called a replacement field; it says where to put the value in the format text. Each format string must have exactly one replacement field. The following replacement fields are allowed:

For field types c, d, x, and o, the element type must be an integer type. For field types e, f, and g, the element type must be a floating-point type. For example, the following format string is illegal, because type string is not an integer type:

For field types e, f, and g, you can optionally specify a precision by writing a decimal point and an integer before the field type. For example, the replacement field {.3f}, specifies fixed-point notation with a precision of 3.

To include the literal character { in the formatted output, you can write {{, and similarly for } and }}. For example, the following definition

specifies a format string element {0} for element value 0.

No other use of { or } in a format string is allowed. For example, this is illegal:

You can include both a default value and a format; in this case, the default value must come first. For example:

If you don’t specify an element format, then each element is displayed using the default format for its type. Therefore, omitting the format string is equivalent to writing the format string "{}".

An array type may have another array type as its element type. In this way you can construct an array of arrays. For example:

When constructing an array of arrays, you may provide any legal default expression, so long as the types are compatible. For example:

As an example, here is a struct type definition that associates the name S with a struct type containing two members: x of type U32, and y of type string:

In general, to write a struct type definition, you write the following:

A struct type member consists of a name, a colon, and a type name, for example x: U32.

The struct type members form an element sequence in which the optional terminating punctuation is a comma. As usual for element sequences, you can omit the comma and use a newline instead. So, for example, we can write the definition shown above in this alternate way:

As noted in the beginning of this section, a type definition is an annotatable element, so you can attach pre and post annotations to it. A struct type member is also an annotatable element, so any struct type member can have pre and post annotations as well. Here is an example:

You can specify an optional default value for a struct definition. To do this, you write the keyword default and an expression that evaluates to a struct value. For example, here is a struct type S with default value { x = 1, y = "abc" }:

A default value expression need not be a literal struct value; it can be any expression with the correct type. For example, you can create a named constant with a struct value and use it multiple times, like this:

If you don’t specify a default value, then the struct type gets an automatic default value, consisting of the default value for each member.

The type of the default expression must match the type of the struct, with type conversions allowed as discussed for struct values. For example, this default expression is allowed, because we can convert integer values to floating-point values, and we can promote a single value to a struct with numeric members:

And this default expression is allowed, because if we omit a member of a struct, then FPP will fill in the member and give it the default value:

However, these default expressions are not allowed:

For any struct member, you can specify that the member is an array of elements. To do this you, write an array the size enclosed in square brackets before the member type. For example:

This definition says that struct S has one element x, which is an array consisting of three U32 values. We call this array a member array.

Member arrays vs. array types: Member arrays let you include an array of elements as a member of a struct type, without defining a separate named array type. Also:

On the other hand, defining a named array is usually a good choice when

In particular, the generated array class provides bounds-checked access operations: it causes a runtime failure if an out-of-bounds access occurs. The bounds checking provides an additional degree of memory safety when accessing array elements.

Member arrays and default values: FPP ignores member array sizes when checking the types of default values. For example, this code is accepted:

The member x of the struct S gets three copies of the value 10 specified for x in the default value expression.

For any struct member, you can include an optional format. To do this, write the keyword format and a format string. The format string for a struct member has the same form as for an array member. For example, the following struct definition specifies that member x should be displayed as a hexadecimal value:

How the entire struct is displayed depends on the implementation. As an example, the value of S with name = "momentum" and offset = 1024 might look like this when displayed:

If you don’t specify a format for a struct member, then the system uses the default format for the type of that member.

If the member has a size greater than one, then the format is applied to each element. For example:

The format string is applied to each of the three elements of the member velocity.

A struct type may have an array or struct type as a member type. In this way you can define a struct that has arrays or structs as members. For example:

When initializing a struct, you may provide any legal default expression, so long as the types are compatible. For example:

For struct values, we said that the order in which the members appear in the value is not significant. For example, the expressions { x = 1, y = 2 } and { y = 2, x = 1 } denote the same value. For struct types, the rule is different. The order in which the members appear is significant, because it governs the order in which the members appear in the generated code.

For example, the type struct S1 { x: U32, y : string } might generate a C++ class S1 with members x and y laid out with x first; while struct S2 { y : string, x : U32 } might generate a C++ class S2 with members x and y laid out with y first. Since class members are generally serialized in the order in which they appear in the class, the members of S1 would be serialized with x first, and the members of S2 would be serialized with y first. Serializing S1 to data and then trying to deserialize it to S2 would produce garbage.

The order matters only for purposes of defining the type, not for assigning default values to it. For example, this code is legal:

FPP struct values have no inherent order associated with their members. However, once those values are assigned to a named struct type, the order becomes fixed.

To define an action, you write the keyword action followed by the name of the action. As with signals, every action name must be unique. To do an action, you write the keyword do followed by a list of action names enclosed in curly braces. You can do this in an initial transition specifier or in a state transition specifier.

As an example, here is the Device state machine from the previous section, with actions added:

Here is the graphical representation:

In this example there are four actions: initialAction1, initialAction2, offOnAction, and onOffAction. The behavior of each of these actions is specified in the C++ implementation; for example, each could emit an F Prime event. The state machine has the following behavior:

When multiple actions appear in an action list, as in the initial transition specifier shown above, the actions occur in the order listed. Each action list is an element sequence with a comma as the optional terminating punctuation.

In addition to doing actions on transitions, a state machine can do actions on entry to or exit from a state. To do actions like this, you write state entry specifiers and state exit specifiers. For example, here is the Device state machine from the previous section, with state entry and exit specifiers added to the ON and OFF states:

Here is the graphical representation:

As with actions on transitions, each entry or exit specifier names a list of actions, and the actions are done in the order named. The entry actions are done just before entering the state, and the exit actions are done just before exiting the state. For example, if the state machine is in state OFF and it receives a cmdOn signal, then it runs the following behavior, in the following order:

Each state may have at most one entry specifier and at most one exit specifier.

Optionally, signals and actions may carry data values. To specify that a signal or action carries a data value, you write a colon and a data type at the end of the signal or action specifier. For example, here is a Device state machine in which the cmdOn signal and the offOnAction each carries a U32 counter value:

When you send the cmdOn signal to an instance of this state machine, you must provide a U32 value. When the state machine is in the OFF state and it receives this signal, it does action offOnAction as shown. The function that defines the behavior of offOnAction has a single argument of type U32. The value provided when the signal is sent is passed as the argument to this function.

Here are the rules for writing typed signals and actions:

Sometimes it is useful to specify that a transition should occur only if a certain condition is true. For example, you may want to turn on a device, but only if it is safe to do so. We call this kind of transition a guarded transition. To specify this transition, you define a guard, which is an abstract function that returns a Boolean value. Then you use the guard in a transition. Here is an example:

Here is the graphical representation:

In this example, there is one guard, powerOnIsSafe. The implementation of this function will return true if it is safe to power on the device; otherwise it will return false. In state OFF, the transition on signal cmdOn is now guarded: when the signal is received in this state, the transition occurs if and only if powerOnIsSafe evaluates to true.

As with actions, each guard must have a unique name. Also as with actions, a guard can have a type; if it does, the type must match the type of the signal at the point where the guard is evaluated. For example, here is a revised version of the previous state machine that adds a value of type DeviceStatus to the guard powerOnIsSafe:

When you send the signal cmdOn to an instance of this state machine, you must provide a value of type DeviceStatus. When the state machine instance evaluates the guard powerOnIsSafe, 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 a self transition. In this case the following behavior occurs:

Note that on a self transition, the state machine exits and reenters S. This behavior is a special case of a more general behavior that we will discuss below in connection with state hierarchy. Below we will also generalize the concept of a self transition to the case of a state with substates.

As an example, consider the following state machine:

Here is the graphical representation:

In this example, when the state machine is in the ON state and it receives a cmdReset signal, the following behavior occurs:

An internal transition is like a self transition, except that there is no exit and reentry. To write an internal transition, you write the on and do parts of a transition and omit the enter part. For example, here is a device state machine with a reset action that causes an internal transition:

Here is the graphical representation:

In this example, when the state machine is in state ON and it receives a cmdReset signal, it does the reset action and performs no other behavior.

An internal transition may have a guard. For example, we could define a guard resetIsSafe and write the internal transition as follows:

As with other transitions, if the signal carries data, then any actions and guards names in an internal transition may carry data of a compatible type.

In this section we explain how to define and use substates.

An example: Here is an example of a state machine with substates:

Here is the graphical representation:

This state machine has four states: ON, OFF, OFF.SAFE, and OFF.UNSAFE. The last two states are substates of OFF. Notice the following:

An instance m of this state machine has the following behavior:

Rules for substates: Here are the rules for defining substates:

Rule 1 ensures that the final target of every transition, after following all initial transition specifiers, is a leaf state, i.e., a state that has no substates.

The hierarchy tree: When a state S is a parent of a state S', we say that S is an ancestor of S' in the state hierarchy. We also say that S is an ancestor of S' if it is a parent of an ancestor of S'. For example, if S is a parent of a parent of S', then S is an ancestor of S'. Note that a state is never an ancestor of itself.

When a state S is a an ancestor of a state S', we say that S' is a descendant of S. For example, S' is a descendant of S if S' is a child of S, or if S' is a child of a child of S. Note that a state is never a descendant of itself.

In order to make the state hierarchy into a tree, we also say that the entire state machine M is a parent of every top-level state in the state machine. This means that (1) M is an ancestor of every state in M and (2) every state in M is a descendant of M. We will say that the tree constructed in this way is the hierarchy tree for M, and that each of M and every state in M is a node in the hierarchy tree. In particular, M is the root node of the hierarchy tree.

In general, when a transition T is defined in a parent state S, T behaves as if it were defined in each of the leaf states that is a descendant of T. In this case we say that T is inherited by each of the leaf states. There is an important exception to this rule: When a state S defines a transition T on a signal s, and a descendant S' of S defines another transition T' on the same signal s, the behavior of T' takes precedence over the inherited transition T in the behavior of S'. This rule is called behavioral polymorphism for transitions.

Example: Here is an example that illustrates inherited transitions and behavioral polymorphism:

Here is the graphical representation:

Here we have rewritten the Device state machine from the previous section so that all the states in that example are descendants of a single state DEVICE. By doing this, we can have a single transition out of DEVICE on signal cmdUnsafe. Before we had to write out the same transition twice, once in the state ON and once in the state OFF.SAFE. Here we can write the transition once in the ancestor state, and it is inherited by all the descendants.

There is one catch, though: in the previous example, we did not define the transition on cmdUnsafe in the state OFF.UNSAFE. Here, if we use inheritance in the obvious way, the transition will be inherited by all the descendants of DEVICE, including OFF.UNSAFE, so the behavior will not be exactly the same as for the previous state machine. This may not matter much in this example, but it would matter if the the state DEVICE.OFF.UNSAFE had entry or exit actions; in this case transition from UNSAFE to itself (which is a self transition) would cause an exit from and reentry to the state, which we may not want.

To remedy this situation, we use behavioral polymorphism. In the state DEVICE.OFF.UNSAFE, we define an internal transition that has an empty list of actions and so does nothing. This transition overrides the transition provided in the ancestor state, so it restores the behavior that, on receipt of the signal cmdUnsafe in the state DEVICE.OFF.UNSAFE, nothing happens.

Syntactic and flattened state transitions: Once we introduce substates and inheritance, it is useful to distinguish syntactic state transitions from flattened state transitions. A syntactic state transition is a state transition in the FPP source for a state machine M. A flattened state transition is a transition that results from applying the rules for transition inheritance to a syntactic state transition. We say the transition is “flattened” because we create it by moving the left side of the transition down to a leaf state. This move flattens the hierarchy on the left side of the transition.

When there is no hierarchy, a syntactic transition from state S₁ to S₂ generates exactly one flattened transition, also from S₁ to S₂. Once we have hierarchy, however, syntactic and flattened state transitions may be different. For example, suppose that S₁ is a parent state, and let T be a syntactic transition from S₁ to S₂. Then for each descendant L of S₁ that is a leaf state, there is a flattened state transition from L to S₂. Note in particular that whereas a syntactic state transition may have a parent state as its source, a flattened state transition always has a leaf state as its source. This distinction between syntactic and flattened state transitions will be useful when we discuss entry and exit actions in the following sections.

Internal transitions: Internal transitions are flattened and inherited like other transitions, except that there is no target state. When a parent state S defines an internal transition, the following occurs:

In previous sections on entry and exit actions and on self transitions, we explained the order in which actions occur during a transition between states without hierarchy. Each of the behaviors described there is a special case of a more general behavior for state machines with hierarchy, which we now describe.

General behavior: Suppose, in the course of running an instance of a state machine M, a flattened state transition T occurs from state L to state S. By the definition of a flattened state transition, we know that L is a leaf state. When carrying out the transition T, the state machine instance will do actions as follows:

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. 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 actions of T, the entry actions of C, and the entry actions of E.

Remember also that if E is not a leaf state, then T will follow one or more transitions to go to a leaf state. In this case, any actions specified in those transitions are done as well, after the transitions described above, and in the order that the initial transitions are run.

Finally, the algorithm above is described in a way that emphasizes ease of understanding. As stated, it is inefficient because it recomputes the least common ancestor every time a flattened state transition occurs. In fact all the sequences of exit and entry actions for flattened state transitions can be computed before generating code, and it is more efficient to do this. This is how the FPP code generator works. For more details, see the algorithm descriptions on the FPP wiki.

The special case of no hierarchy: The general behavior described above agrees with the special-case behavior that we described in the section on entry and exit actions for state machines without hierarchy. When a state machine M has no hierarchy, a every state transition T is a flattened transition that goes from a leaf state L to a leaf state S, both of which are children of M in the hierarchy tree. So we always exit L, do the actions of T, and enter S.

In particular, the general behavior agrees with the behavior that we previously described for self transitions. When L and S are the same leaf state, the least common ancestor of L and S is the parent P of S. So we exit S to go up to P, do the actions of T, and reenter S.

Let S₁ and S₂ be states. If S₁ is equal to S₂, or S₁ is an ancestor of S₂, or S₂ is an ancestor of S₁, then we say that S₁ and S₂ are directly related in the hierarchy tree.

In this section we describe the behavior of transitions between directly related states. Each of the behaviors described below follows from the general behavior presented in the previous section. However, in some cases the behavior may be subtle or surprising.

Flattened transitions to ancestors: When a transition T goes from a leaf state L to a state A that is an ancestor of L, we call T a flattened transition to an ancestor. The least common ancestor of L and A is the parent P of A. Therefore the following behavior occurs:

Syntactic transitions to ancestors: Consider a state transition T of the form on s enter A that is defined in the state S, where A is an ancestor of S. We call this kind of state transition a syntactic transition to an ancestor. If S is a leaf state, then it represents a flattened transition to the ancestor A. Otherwise it represents one flattened transition to the ancestor A for each descendant of S that is a leaf state. Because of behavioral polymorphism, any of the flattened transitions may be overridden.

Flattened transitions to self: A flattened transition to self is a transition from a leaf state L to itself. This is what we previously called a self transition.

Syntactic transitions to self: Consider a state transition T of the form on s enter S that is defined in the state S. In general we call this kind of state transition a syntactic transition to self. If S is a leaf state, then T a flattened transition to self. In particular, when there is no hierarchy, every syntactic transition to self is a self transition. If S is not a leaf state, then T is flattened to one or more transitions from leaf states L that are descendants of S. Each of these transitions is a flattened transition to the ancestor S. Because of behavioral polymorphism, any of the flattened transitions may be overridden.

Flattened transitions to descendants: In theory, a flattened transition to a descendant would be a transition from a leaf node L to a descendant D of L. However, leaf nodes have no descendants, so no such transition is possible. We include the category for completeness. It has no members.

Syntactic transitions to descendants: Consider a state transition T of the form on s enter D that is defined in the state S, where D is a descendant of S. We call this kind of state transition a syntactic transition to a descendant. By symmetry with syntactic transitions to ancestors, you might expect that the first behavior when making such a transition is to exit and reenter S. However, this is not what happens. Instead, T represents one flattened transition from each leaf state that is a descendant of S. The flattened transitions have the following properties:

In either case, because of behavioral polymorphism, any of the flattened transitions may be overridden.

Like state definitions, choice definitions are hierarchical. That is, you may define a choice inside a state. The names of choices are qualified by the enclosing state names as for the names of substates. For example, you can write this:

The dots represent omitted text needed to make the state machine valid. In this example, the qualified name of the choice is S.C. Inside state S, you can refer to the choice as S.C or C. Outside state S, you must refer to it as S.C.

Initial transitions to choices: When an initial transition I goes to a choice C, C and I must have the same parent P in the hierarchy tree. In addition, each transition out of C must go to a state or choice with parent P; and if it goes to a choice, then each transition out of that choice must go to a state or choice with parent P, and so forth. Another way to say this is that (since no cycles of transitions through choices are allowed) each transition path out of I must go through zero or more choices with parent P to a state with parent P.

For example, this state machine is allowed:

But this one is not:

Entry and exit actions: As in the non-hierarchical case, when a transition T of a state machine M goes to or from a choice, entry and exit actions occur as if each choice were a leaf state with no entry or exit actions. For example, suppose that M has a state S with substates A and B, A has a choice C, and B has substate B'. Suppose that T goes from C to B'. Then least common ancestor is S, and the following actions would be done, in the following order: the exit actions of A, the actions of T, the entry actions of B, and the entry actions of B'.

The simplest port instance specifies a kind, a name, and a type. The kind is one of the following:

The name is the name of the port instance. The type refers to a port definition.

As an example, here is a passive component F32Adder that adds two F32 values and produces an F32 value.

There are two sync input port instances and one output port instance. The kind appears first, followed by the keyword port, the port instance name, a colon, and the type. Each port instance is an annotatable element, so you can annotate the instances as shown.

As another example, here is an active version of F32Adder with async input ports:

In each case, the adding is done in the target language. For example, in the C++ implementation, you would generate a base class with a virtual handler function, and then override that virtual function in a derived class that you write. For further details about implementing F Prime components, see the F Prime User Manual.

Note on terminology: As explained above, there is a technical distinction between a port type (defined outside any component, and providing the type of a port instance) and a port instance (specified inside a component and instantiating a port type). However, it is sometimes useful to refer to a port instance with the shorter term "port" when there is no danger of confusion. We will do that in this manual. For example, we will say that the F32Adder component has three ports: two async input ports of type F32Value and one output port of type F32Value.

The port instances appearing in a component definition must satisfy certain rules. These rules ensure that the FPP model makes sense.

First, no passive component may have an async input port. This is because a passive component has no message queue, so asynchronous input is not possible. As an example, if we modify the input ports of our F32Adder to make them async, we get an error.

Try presenting this code to fpp-check and observe what happens.

Second, an active or queued component must have asynchronous input. That means it must have at least one async input port; or it must have an internal port; or it must have at least one async command; or it must have at least one state machine instance. Internal ports, async commands, and state machine instances are described below. As an example, if we modify the input ports of our ActiveF32Adder to make them sync, we get an error, because there is no async input.

Third, a port type appearing in an async input port may not have a return type. This is because returning a value makes sense only for synchronous input. As an example, this component definition is illegal:

When you specify a port instance as part of an FPP component, you are actually specifying an array of port instances. Each instance has a port number, where the port numbers start at zero and go up by one at each successive element. (Another way to say this is that the port numbers are the array indices, and the indices start at zero.)

If you don’t specify a size for the array, as shown in the previous sections, then the array has size one, and there is a single port instance with port number zero. Thus a port instance specifier with no array size acts like a singleton element. Alternatively, you can specify an explicit array size. You do that by writing an expression enclosed in square brackets [ …​ ] denoting the size (number of elements) of the array. The size expression must evaluate to a numeric value. As with array type definitions, the size goes before the element type. As an example, here is another version of the F32Adder component, this time using a single array of two input ports instead of two named ports.

For async input ports, you may specify a priority. The priority specification is not allowed for other kinds of ports. To specify a priority, you write the keyword priority and an expression that evaluates to a numeric value after the port type. As an example, here is a modified version of the ActiveF32Adder with specified priorities:

If an async input port has no specified priority, then the translator uses a default priority. The precise meaning of the default priority and of the numeric priorities is implementation-specific. In general the priorities regulate the order in which elements are dispatched 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. A FSW assertion is a condition that must be true in order for FSW execution to proceed safely. The behavior of a FSW assertion failure is configurable in the C++ implementation of the F Prime framework; typically it causes a FSW abort and system reset.

Optionally, you can specify the behavior when a message received on an async input port causes a queue overflow. There are three possible behaviors:

To specify queue full behavior, you write one of the keywords assert, block, drop, or hook after the port type and after the priority (if any). As an example, here is the ActiveF32Adder updated with explicit queue full behavior.

As for priority specifiers, queue full specifiers are allowed only for async input ports.

When writing a port instance, instead of specifying a named port type, you may write the keyword serial. Doing this specifies a serial port instance. A serial port instance does not specify the type of data that it carries. It may be connected to a port of any type. Serial data passes through the port; the data may be converted to or from a specific type at the other end of the connection.

As an example, here is a passive component for taking a stream of serial data and splitting it (i.e., repeating it by copy) onto several streams:

By using serial ports, you can send several unrelated types of data over the same port connection. This technique is useful when communicating across a network: on each side of the network connection, a single component can act as a hub that routs all data to and from components on that side. This flexibility comes at the cost that you lose the type compile-time type checking provided by port connections with named types. For more information about serial ports and their use, see the F Prime User Manual.

A command is an instruction to the spacecraft to perform an action. Each component instance C that specifies commands has the following high-level behaviors:

In FPP, the keywords for the special command behaviors are as follows:

Collectively, these ports are known as command ports. To specify a command port, you write one of the keyword pairs shown above followed by the keyword port and the port name.

As an example, here is a passive component CommandPorts with each of the command ports:

Any component may have at most one of each kind of command port. If a component receives commands (more on this below), then all three ports are required. The port names shown in the example above are standard but not required; you can use any names you wish.

During translation, each command port is converted into a typed port instance with a predefined port type, as follows:

The F Prime framework provides definitions for these ports in the directory Fw/Cmd. For checking simple examples, you can use the following simplified definitions of these ports:

For example, to check the CommandPorts component, you can add these lines before the component definition. If you don’t do this, or something similar, then the component definition won’t pass through fpp-check because of the missing ports. (Try it and see.)

Note that the port definitions shown above are for conveniently checking simple examples only. They are not correct for the F Prime framework and will not work properly with F Prime C++ code generation.

For further information about command registration, receipt, and response, and implementing command handlers, see the F Prime User Manual.

An event is a report that something happened, for example, that a file was successfully uplinked. The special event behaviors, and their keywords, are as follows:

Collectively, these ports are known as event ports. To specify an event port, you write one of the keyword groups shown above followed by the keyword port and the port name.

As an example, here is a passive component EventPorts with each of the event ports:

Any component may have at most one of each kind of event port. If a component emits events (more on this below), then both event ports are required.

During translation, each event port is converted into a typed port instance with a predefined port type, as follows:

The name Log refers to an event log. The F Prime framework provides definitions for these ports in the directory Fw/Log. For checking simple examples, you can use the following simplified definitions of these ports:

For further information about events in F Prime, see the F Prime User Manual.

Telemetry is data regarding the state of the system. A telemetry port allows a component to emit telemetry. To specify a telemetry port, you write the keyword telemetry, the keyword port, and the port name.

As an example, here is a passive component TelemetryPorts with a telemetry port:

Any component may have at most one telemetry port. If a component emits telemetry (more on this below), then a telemetry port is required.

During translation, each telemetry port is converted into a typed port instance with the predefined port type Fw.Tlm. The F Prime framework provides a definition for this port in the directory Fw/Tlm. For checking simple examples, you can use the following simplified definition of this port:

For further information about telemetry in F Prime, see the F Prime User Manual.

A parameter is a configurable constant that may be updated from the ground. The current parameter values are stored in an F Prime component called the parameter database.

The special parameter behaviors, and their keywords, are as follows:

Collectively, these ports are known as parameter ports. To specify a parameter port, you write one of the keyword groups shown above followed by the keyword port and the port name.

As an example, here is a passive component ParamPorts with each of the parameter ports:

Any component may have at most one of each kind of parameter port. If a component has parameters (more on this below), then both parameter ports are required.

During translation, each parameter port is converted into a typed port instance with a predefined port type, as follows:

The F Prime framework provides definitions for these ports in the directory Fw/Prm. For checking simple examples, you can use the following simplified definitions of these ports:

For further information about parameters in F Prime, see the F Prime User Manual.

A time get port allows a component to get the system time from a time component. To specify a time get port, you write the keywords time get, the keyword port, and the port name.

As an example, here is a passive component TimeGetPorts with a time get port:

Any component may have at most one time get port. If a component emits events or telemetry (more on this below), then a time get port is required, so that the events and telemetry points can be time stamped.

During translation, each time get port is converted into a typed port instance with the predefined port type Fw.Time. The F Prime framework provides a definition for this port in the directory Fw/Time. For checking simple examples, you can use the following simplified definition of this port:

For further information about time in F Prime, see the F Prime User Manual.

A data product is a collection of data that can be stored to an onboard file system, given a priority, and downlinked in priority order. For example, a data product may be an image or a unit of science data. Data products are stored in containers that contain records. A record is a unit of data. A container stores (1) a header that describes the container and (2) a list of records.

The special data product behaviors, and their keywords, are as follows:

Collectively, these ports are known as data product ports. To specify a data product port, you write one of the keyword groups shown above followed by the keyword port and the port name. To specify a product receive port, you must first write async, sync or guarded to specify whether the input port is asynchronous, synchronous, or guarded, as described in the section on basic port instances. When specifying an async product receive port, you may specify a priority behavior or queue full behavior.

As an example, here is a passive component DataProductPorts with each of the data product ports:

Any component may have at most one of each kind of data product port. If a component defines data products (more on this below), then there must be (1) a product get port or a product request port and (2) a product send port. If there is a product request port, then there must be a product receive port.

During translation, each data product port is converted into a typed port instance with a predefined port type, as follows:

The F Prime framework provides definitions for these ports in the directory Fw/Dp. For checking simple examples, you can use the following simplified definitions of these ports:

For further information about data products in F Prime, see the data products documentation in the F Prime repository.

The simplest command consists of a kind followed by the keyword command and a name. The kind is one of the following:

Notice that the kinds of commands are similar to the kinds of input ports. The name is the name of the command.

As an example, here is an active component called Action with two commands: an async command START and a sync command STOP.

Command START is declared async. That means that when a START command is dispatched to an instance of this component, it arrives on a queue. Later, the F Prime framework takes the message off the queue and calls the corresponding handler on the thread of the component.

Command STOP is declared sync. That means that the command runs immediately on the thread of the invoking component (for example, a command dispatcher component). Because the command runs immediately, its handler should be very short. For example, it could set a stop flag and then exit.

Notice that we defined the three command ports for this component. All three ports are required for any component that has commands. As an example, try deleting one or more of the command ports from the code above and running the result through fpp-check.

async commands require a message queue, so they are allowed only for active and queued components. As an example, try making the Action component passive and running the result through fpp-check.

When specifying a command, you may specify one or more formal parameters. The parameters are bound to arguments when the command is sent to the spacecraft. Different uses of the same command can have different argument values.

The formal parameters of a command are the same as for a port definition, except for the following:

As an example, here is a Switch component that has two states, ON and OFF. The component has a SET_STATE command for setting the state. The command has a single argument state that specifies the new state.

In this example, the enum type State is a displayable type because its definition is known to FPP. Try replacing the enum definition with the abstract type definition type S and see what happens when you run the model through fpp-check. Remember to provide stubs for the special command ports that are required by fpp-check.

Every command in an F Prime FSW application has an opcode. The opcode is a number that uniquely identifies the command. The F Prime framework uses the opcode when dispatching commands because it is a more compact identifier than the name. The name is mainly for human interaction on the ground.

The opcodes associated with each component C are relative to the component. Typically the opcodes start at zero: that is, the opcodes are 0, 1, 2, etc. When constructing an instance I of component C, the framework adds a base opcode for I to each relative opcode associated with C to form the global opcodes associated with I. That way different instances of C can have different opcodes for the same commands defined in C. We will have more to say about base and relative opcodes when we describe component instances and topologies.

If you specify a command c with no explicit opcode, as in the examples shown in the previous sections, then FPP assigns a default opcode to c. The default opcode for the first command in a component is zero. Otherwise the default opcode for any command is one more than the opcode of the previous command.

It is usually convenient to rely on the default opcodes. However, you may wish to specify one or more opcodes explicitly. To do this, you write the keyword opcode followed by a numeric expression after the command name and after the formal parameters, if any. Here is an example:

Within a component, the command opcodes must be unique. For example, this component is incorrect because the opcode zero appears twice:

When specifying an async command, you may specify priority and queue full behavior as for an async input port. You put the priority and queue full information after the command name and after the formal parameters and opcode, if any. Here is an example:

Priority and queue full behavior are allowed only for async commands. Try changing one of the commands in the previous example to sync and see what fpp-check has to say about it.

The simplest event consists of the keyword event, a name, a severity, and a format string. The name is the name of the event. A severity is the keyword severity and one of the following:

A format is the keyword format and a literal string for use in a formatted real-time display or event log.

As an example, here is an active component called BasicEvents with a few basic events.

Notice that we defined the two event ports and a time get port for this component. All three ports are required for any component that has events. As an example, try deleting one or more of these ports from the code above and running the result through fpp-check.

When specifying an event, you may specify one or more formal parameters. The parameters are bound to arguments when the component instance emits the event. The argument values appear in the formatted text that describes the event.

You specify the formal parameters of an event in the same way as for a command specifier. For each formal parameter, there must be a corresponding replacement field in the format string. The replacement fields for event format strings are the same as for format strings in type definitions. The replacement fields in the format string match the event parameters, one for one and in the same order.

As an example, here is a component with two events, each of which has formal parameters. Notice how the replacement fields in the event format strings correspond to the formal parameters.

Every event in an F Prime FSW application has a unique numeric identifier. As for command opcodes, the event identifiers for a component are specified relative to the component, usually starting from zero and counting up by one. If you omit the identifier, then FPP assigns a default identifier: zero for the first event in the component; otherwise one more than the identifier of the previous event.

If you wish, you may explicitly specify one or more event identifiers. To do this, you write the keyword id followed by a numeric expression immediately before the keyword format. Here is an example:

Within a component, the event identifiers must be unique.

Sometimes it is necessary to throttle events, to ensure that they do not flood the system. For example, suppose that the FSW requests some resource R at a rate r of several times per second. Suppose further that if R is unavailable, then the FSW emits a warning event. In this case, we typically do not want the FSW to emit an unbounded number of warnings at rate r; instead, we want it to emit a single warning or a few warnings.

To achieve this behavior, you can write the keyword throttle and a numeric expression after the format string. The expression must evaluate to a constant value n. After an instance of the component has emitted the event n times, it will stop emitting the event. Here is an example:

In this example, event E will be throttled after the component instance has emitted it ten times.

Once an event is throttled, the component instance will no longer emit the event until the throttling is canceled. Typically, the canceling happens via a FSW command. For details, see the F Prime User Manual.

The simplest telemetry channel consists of the keyword telemetry, a name, and a data type. The name is the name of the channel. The data type is the type of data carried on the channel. The data type must be a displayable type.

As an example, here is an active component called BasicTelemetry with a few basic events.

Notice that we defined a telemetry port and a time get port for this component. Both ports are required for any component that has telemetry.

Every telemetry channel in an F Prime FSW application has a unique numeric identifier. As for command opcodes and event identifiers, the telemetry channel identifiers for a component are specified relative to the component, usually starting from zero and counting up by one. If you omit the identifier, then FPP assigns a default identifier: zero for the first event in the component; otherwise one more than the identifier of the previous channel.

If you wish, you may explicitly specify one or more telemetry channel identifiers. To do this, you write the keyword id followed by a numeric expression immediately after the data type. Here is an example:

Within a component, the telemetry channel identifiers must be unique.

You can specify how often the telemetry is emitted on a channel C. There are two possibilities:

Emitting telemetry on change can reduce unnecessary activity in the system. For example, suppose a telemetry channel C counts the number of times that some event E occurs in a periodic task, and suppose that E does not occur on every cycle. If you declare channel C on change, then your implementation can call the telemetry emit function for C on every cycle, and telemetry will be emitted only when E occurs.

To specify an update frequency, you write the keyword update and one of the frequency selectors shown above. The update specifier goes after the type name and after the channel identifier, if any. If you don’t specify an update frequency, then the default value is always. Here is an example:

You may specify how a telemetry channel is formatted in the ground display. To do this, you write the keyword format and a format string with one replacement field. The replacement field must match the type of the telemetry channel. The format specifier comes after the type name, after the channel identifier, and after the update specifier.

Here is an example:

You may specify limits, or bounds, on the expected values carried on a telemetry channel. There are two kinds of limits: low (meaning that the values on the channel should stay above the limit) and high (meaning that the values should stay below the limit). Within each kind, there are three levels of severity:

The F Prime ground data system displays an appropriate warning when a telemetry point crosses a limit.

The limit specifiers come after the type name, identifier, update specifier, and format string. You specify the low limits (if any) first, and then the high limits. For the low limits, you write the keyword low followed by a list of limits in curly braces { …​ }. For the high limits, you do the same thing but use the keyword high. Each limit is a severity keyword followed by a numeric expression. Here are some examples:

Each limit must be a numeric value. The type of the telemetry channel must be (1) a numeric type; or (2) an array or struct type each of whose members has a numeric type; or (3) an array or struct type each of whose members satisfies condition (1) or condition (2).

The simplest parameter consists of the keyword param, a name, and a data type. The name is the name of the parameter. The data type is the type of data stored in the parameter. The data type must be a displayable type.

As an example, here is an active component called BasicParams with a few basic parameters.

Notice that we defined the two parameter ports for this component. Both ports are required for any component that has parameters.

Notice also that we defined the command ports for this component. When you add one or more parameters to a component, F Prime automatically generates commands for (1) setting the local parameter in the component and (2) saving the local parameter to a system-wide parameter database. Therefore, any component that has parameters must have the command ports. Try deleting one or more of the command ports from the example 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 available in the parameter database. If you don’t specify a default value, and no value is available in the database, then attempting to get the parameter produces an invalid value. What happens then is up to the FSW implementation. By providing default values for your parameters, you can avoid handling this case.

Here is the example from the previous section, updated to include default values for the parameters:

Every parameter in an F Prime FSW application has a unique numeric identifier. As for command opcodes, event identifiers, and telemetry channel identifiers, the parameter identifiers for a component are specified relative to the component, usually starting from zero and counting up by one. If you omit the identifier, then FPP assigns a default identifier: zero for the first event in the component; otherwise one more than the identifier of the previous parameter.

If you wish, you may explicitly specify one or more parameter identifiers. To do this, you write the keyword id followed by a numeric expression after the data type and after the default value, if any. Here is an example:

Within a component, the parameter identifiers must be unique.

Each parameter that you specify has two implied commands: one for setting the value bound to the parameter locally in the component, and one for saving the current local value to the system-wide parameter database. The opcodes for these implied commands are called the set and save opcodes for the parameter.

By default, FPP generates set and save opcodes for a parameter P according to the following rules:

If you wish, you may specify either or both of the set and save opcodes explicitly. To specify the set opcode, you write the keywords set opcode and a numeric expression. To specify the save opcode, you write the keywords save opcode and a numeric expression. The set and save opcodes come after the type name, default parameter value, and parameter identifier. If both are present, the set opcode comes first.

When you specify an explicit set or save opcode o, the default value for the next opcode is o + 1. Here is an example:

In F Prime, a data product is represented as a container. One container holds one data product, and each data product is typically stored in its own file. A container consists of a header, which provides information about the container (e.g., the size of the data payload), and binary data representing a list of serialized records. A record is a unit of data. For a complete specification of the container format, see the documentation on F Prime framework support for data products.

In an F Prime component, you can specify one or more containers and one or more records. The simplest container specification consists of the keywords product container and a name. The name is the name of the container. The simplest record specification consists of the keywords product record, a name, and a data type. The name is the name of the record. The data type is the type of the data that the record holds.

As an example, here is a component called BasicDataProducts that specifies two records and two containers.

The FPP back end uses this specification to generate code for requesting buffers to hold containers and for serializing records into containers. See the F Prime data products documentation for the details.

Note the following:

Every record in an F Prime FSW application has a unique numeric identifier. As for command opcodes, event identifiers, telemetry channel identifiers, and parameters, the record identifiers for a component are specified relative to the component, usually starting from zero and counting up by one. If you omit the identifier, then FPP assigns a default identifier: zero for the first event in the component; otherwise one more than the identifier of the previous parameter. The same observations apply to containers and container identifiers.

If you wish, you may explicitly specify one or more container or record identifiers. To do this, you write the keyword id followed by a numeric expression at the end of the container or record specifier. Here is an example:

Within a component, the record identifiers must be unique, and the container identifiers must be unique.

In the basic form of a record described above, each record that does not have string type has a fixed, statically-specified size. The record may contain an array (e.g., an array type or a struct type with a member array), but the size of the array must be specified in the model. To specify a record that is a dynamically-sized array, you put the keyword array after the type specifier for the record. For example:

In this example, a record with name DataArrayRecord holds an array of elements of type Data. The number of elements is unspecified in the model; it is provided when the record is serialized into a container.

To instantiate a passive component, you write the following:

The base identifier must resolve to a number. The FPP translator adds this number to each of the component-relative command opcodes, event identifiers, telemetry channel identifiers, and parameter identifiers specified in the component, as discussed in the previous section. The base identifier for the instance plus the component-relative opcode or identifier for the component gives the corresponding opcode or identifier for the instance.

Here is an example:

We have defined a passive component Sensors.EngineTemp with three ports: a schedule input port for driving the component periodically on a rate group, a time get port for getting the time, and a telemetry port for reporting telemetry. (For more information on rate groups and the use of Svc.Sched ports, see the F Prime documentation.) We have given the component two telemetry channels: ImpulseTemp for reporting the temperature of the impulse engine, and WarpTemp for reporting the temperature of the warp core.

Next we have defined an instance FSW.engineTemp of component Sensors.EngineTemp. Because the instance definition is in a different module from the component definition, we must refer to the component by its qualified name Sensors.EngineTemp. If we wrote

the FPP compiler would complain that the symbol EngineTemp is undefined (try it and see).

We have specified that the base identifier of instance FSW.engineTemp is the hexadecimal number 0x100 (256 decimal). In the component definition, the telemetry channel ImpulseTemp has relative identifier 0, and the telemetry channel WarpTemp has relative identifier 1. Therefore the corresponding telemetry channels for the instance FSW.engineTemp have identifiers 0x100 and 0x101 (256 and 257) respectively.

For consistency, the base identifier is required for all component instances, even instances that define no dictionary elements (commands, events, telemetry, or parameters). For each component instance I, the range of numbers between the base identifier and the base identifier plus the largest relative identifier is called the identifier range of I. If a component instance defines no dictionary elements, then the identifier range is empty. All the numbers in the identifier range of I are reserved for instance I (even if they are not all used). No other component instance may have a base identifier that lies within the identifier range of I.

For example, this code is illegal:

The base identifier 0x101 for rightEngineTemp is inside the identifier range for leftEngineTemp, which goes from 0x100 to 0x101, inclusive.

XML limitation: The tool that generates the XML dictionary requires that each component instance I have a distinct base ID, even if I defines no dictionary elements.

Instantiating a queued component is just like instantiating a passive component, except that you must also specify a queue size for the instance. You do this by writing the keywords queue size and the queue size after the base identifier. Here is an example:

In the component definition, we have revised the example from the previous section so that the EngineTemp component is queued instead of passive, and we have added an async input port for calibration input. 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 that configure the OS thread associated with each component instance.

Queue size, stack size, and priority: When instantiating an active component, you must specify a queue size, and you may specify either or both of a stack size and priority. You specify the queue size in the same way as for a queued component. You specify the stack size by writing the keywords stack size and the desired stack size in bytes. You specify the priority by writing the keyword priority and a numeric priority. The priority number is passed to the OS operation for creating the thread, and its meaning is OS-specific.

Here is an example:

We have defined an active component Utils.DataCompressor for compressing data. We have defined an instance of this component called FSW.dataCompressor. Our instance has base identifier 0x100, the default queue size, the default stack size, and priority 30. We have used constant definitions for the default queue and stack sizes.

We could also have omitted either or both of the stack size and priority specifiers. When you omit the stack size or priority from a component instance definition, F Prime supplies a default value appropriate to the target platform. With implicit stack size and priority, the dataCompressor instance looks like this:

CPU affinity: When defining an active component, you may specify a CPU affinity. The CPU affinity is a number whose meaning depends on the platform. Usually it is an instruction to the operating system to run the thread of the active component on a particular CPU, identified by number.

To specify CPU affinity, you write the keyword cpu and the CPU number after the queue size, the stack size (if any), and the priority specifier (if any). For example:

This example is the same as the previous dataCompressor instance, except that we have specified that the thread associated with the instance should run on CPU 0.

With implicit stack size and priority, the example looks like this:

The FPP translator uses init specifiers when it generates code for an F Prime topology. We will have more to say about topology generation in the next section. For now, you just need to know the following:

The generated code in T TopologyAc.hpp and T TopologyAc.cpp is divided into several phases of execution. Table Execution Phases shows the execution phases recognized by the FPP code generator. In this table, T is the name of a topology and I is the name of a component instance. The columns of the table have the following meanings:

You will most often need to write code for configConstants, configObjects, and configComponents. These phases often require implementation-specific input that cannot be provided in any other way, except to write an init specifier.

In theory you should never have to write code for instances or initComponents — this code can be be standardized — but in practice not all F Prime components conform to the standard, so you may have to override the default.

You will typically not have to write code for regCommands, readParameters, and loadParameters — the framework can generate this code automatically — except that the parameter database instance needs one line of special code for reading its parameters.

Code for startTasks, stopTasks, and freeThreads is required only if the user-written implementation of a component instance manages its own F Prime task. If you use a standard F Prime active component, then the framework manages the task, and this code is generated automatically.

Code for tearDownComponents is required only if a component 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. The init specifiers, if any, come at the end of the definition and must be enclosed in curly braces. The init specifiers form an element sequence with a semicolon as the optional terminating punctuation.

To write an init specifier, you write the following:

It is usually convenient, but not required, to use a multiline string for the code snippet.

As an example, here is the component instance definition for the command sequencer instance cmdSeq from the F Prime system reference deployment:

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 generation of names.

The code for configComponents calls allocateBuffer, passing in an allocator object that is declared elsewhere. (In the section on implementing deployments, we will explain where this allocator object is declared.) The code for tearDownComponents calls deallocateBuffer to deallocate the sequence buffer, passing in the allocator object again.

As another example, here is the instance definition for the parameter database instance prmDb from the system reference deployment:

Here we provide code for the instances phase because the constructor call for this component is nonstandard — it takes the parameter file name as an argument. In the readParameters phase, we provide the code for reading the parameters from the file. As discussed above, this code is needed only for the parameter database instance.

When writing init specifiers, you may read (but not modify) a special value state that you define in a handwritten main function. This value lets you pass application-specific information from the handwritten code to the auto-generated code. We will explain the special state value further in the section on implementing deployments.

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.

A direct graph specifier provides a name and a list of connections. We illustrated direct graph specifiers in the previous section, where the simple topology example included direct graph specifiers for graphs named C1 and C2. Here are some more details about direct graph specifiers.

As shown in the previous section, each connection consists of an output port specifier, followed by an arrow, followed by an input port specifier. For example:

Each of the two port specifiers consists of a component instance name, followed by a dot, followed the name of a port instance. The component instance name must refer to a component instance definition and may be qualified by a module name. For example:

Here component instance a is defined in module M and component instance b is defined in module N. In a port specifier a.p, the port instance name p must refer to a port instance of the component definition associated with the component instance a.

Each component instance named in a connection must be part of the instance list in the topology. For example, if you write a connection a.b -> c.d inside a topology T, and the specifier instance a does not appear inside topology T, then you will get an error — even if a is a valid instance name for the FPP model. The reason for this rule is that in flight code we need to be very careful about which instances are included in the application. Naming all the instances also lets us check for unconnected ports.

You may use the same name in more than one direct graph specifier in the same topology. If you do this, then all specifiers with the same name are combined into a single graph with that name. For example, this code

is equivalent to this code:

The members of a direct graph specifier form an element sequence in which the optional terminating punctuation is a comma. For example, you can write this:

The connections appearing in direct graph specifiers must obey the following rules:

A few connection patterns are so common in F Prime that they get special treatment in FPP. For example, an F Prime topology typically includes an instance of the component Svc.Time. This component has a port timeGetPort of type Fw.Time that other components can use to get the system time. Any component that gets the system time (and there are usually several) has a connection to the timeGetPort port of the Svc.Time instance.

Suppose you are constructing a topology in which (1) sysTime is an instance of Svc.Time; and (2) each of the instances a, b, c, etc., has a time get port timeGetOut port connected to sysTime.timeGetPort, If you used a direct graph specifier to write all these connections, the result might look like this:

This works, but it is tedious and repetitive. So FPP provides a better way: you can use a pattern graph specifier to specify this common pattern. You can write

This code says the following:

The result is as if you had written the direct graph specifier yourself. All the other rules for direct graph specifiers apply: for example, if you write another direct graph specifier with name Time, then the connections in that specifier are merged with the connections generated by the pattern specifier.

In the example above, we call time the kind of the pattern graph specifier. We call sysTime the source instance of the pattern. It is the source of all the time pattern connections in the topology. We call the instances that have time get ports (and so contribute connections to the pattern) the target instances. They are the instances targeted by the pattern once the source instance is named.

Table Pattern Graph Specifiers shows the pattern graph specifiers allowed in FPP. The columns of the table have the following meanings:

The command pattern specifier generates three connection graphs: Command, CommandRegistration, and CommandResponse.

Here are some rules for writing graph pattern specifiers:

The default behavior for a pattern is to generate the connections for all target instances as shown in the table. If you wish, you may generate connections for a selected set of target instances. To do this, you write a list of target instances enclosed in curly braces after the source instance. For example, suppose a topology contains instances a, b, and c each of which has an output port that satisfies the time pattern. And suppose that sysTime is an instance of Svc.Time. Then if you write this pattern

you will get a connection graph Time containing time connections from each of a, b, and c to sysTime. But if you write this pattern

then you will just get the connections from a and b to sysTime. The instances a and b must be valid target instances for the pattern.

As with connections, you can write the instances a and b each on its own line, or you can separate them with commas:

To use explicit numbering, you provide an explicit port number for a connection endpoint. You write the port number as a numeric expression in square brackets, immediately following the port name. The port numbers start at zero.

For example, the RateGroups graph of the Ref (reference) topology in the F Prime repository defines the rate group connections. It contains the following connection:

The first line says to connect the port at index Ports.RateGroups.rateGroup1 of rateGroupDriverComp.CycleOut to rateGroup1Comp.CycleIn. The symbol Ports.RateGroups.rateGroup1 is an enumerated constant, defined like this:

The second and following lines say to connect the ports of rateGroup1Comp.RateGroupMemberOut at the indices 0, 1, 2, and 3 in the manner shown.

As another example, the Downlink graph of the reference topology contains the following connection:

This line says to connect downlink.framedAllocate to staticMemory.bufferAllocate at index Port.StaticMemory.downlink. Again the port index is a symbolic constant.

If you wish, you may write two explicit port numbers, one at each endpoint. For example:

Here are some rules to keep in mind when using explicit numbering:

Automatic matching: After resolving explicit numbering, the FPP translator applies matched numbering. In this step, the translator numbers all pairs of matched ports.

Matched numbering is essential for resolving the command and health patterns, each of which has matched ports. You can also use matched numbering in conjunction with direct graph specifiers. For example, the Ref topology contains the following connections:

The port cmdDisp.seqCmdBuff port of the command dispatcher receives command input from the command sequencer or from the ground. The corresponding command response goes out on port cmdDisp.seqCmdStatus. These two ports are matched in the definition of the Command Sequencer component.

When you use matched numbering with direct graph specifiers, you must obey the following rules:

If you violate these rules, you will get an error during analysis. You can relax these rules by writing unmatched connections, as described below.

Unmatched connections: Occasionally you may need to relax the rules for using matched ports. For example, you may need to match pairs of connections that use the F Prime hub pattern to cross a network boundary. In this case, although the connections are logically matched at the endpoints, they all go through a single hub instance on the side of the boundary that has the matched ports, and so they do not obey the simple rules for matching given here.

When a connection goes to or from a matched port, we say that it is match constrained. Ordinarily a match constrained connection must obey the rules for matching stated above. To relax the rules, you can write an unmatched connection. To do this, write the keyword unmatched at the start of the connection specifier. Here is an example:

In this example, there are two pairs of connections between the pIn and pOut connections of the instances source and target. The ports of source are match constrained, so ordinarily the connections would need to obey the matching rules. The connections do partially obey the rules: for example, there are no duplicate numbers, and the numbers match. However, both pairs of connections go to and from the same instance target; ordinarily this is not allowed for match constrained connections. To allow it, we need to use unmatched ports as shown.

Note the following about using unmatched ports:

Manual matching: Port matching specifiers work well when each matched pair of connections goes between the same two components, one of which has a matched pair of ports. If the matching does not follow this pattern, then automatic matched numbering will not work, and it is usually better not to use a port matching specifier at all. Instead, you can use explicit port numbers to express the matching. For example, the Ref topology contains these connections:

In this case the staticMemory instance requires that pairs of allocation and deallocation requests for the same memory go to the same port. But the allocation request comes from comm, and the deallocation request comes from uplink. Since the allocation and deallocation connections go to different component instances, we can’t used automatic matched numbering. Instead we define a symbolic constant Ports.StaticMemory.uplink and use that twice to do the matching by hand.

After resolving explicit numbering and matched numbering, the FPP translator applies general numbering. In this step, the translator uses the following algorithm to fill in any remaining unassigned port numbers:

For example, consider the following connections:

After general numbering, the connections could be numbered as follows:

To import a topology A into a topology B, you write import A inside topology B, like this:

You may add instances and connections as usual to B, as shown by the dots.

When you do this, the FPP translator does the following:

For example, suppose topologies A and B are defined as follows:

After import resolution, B is equivalent to this topology:

Notice that the C1 connections of A are merged with the C1 connections of B.

Often when importing topology A into topology B, you want to include one or more instances in A that exist just for running A, but that you don’t want imported into B. For example, A could have an instance cStub which is a stub version of a component c that is fully implemented in B. In this case

To handle this case, you can make cStub a private instance of A and c an instance of B. When you import B into A, cStub will not become an instance of B. Further, no connections in A involving cStub will be imported into B.

As an example, suppose we revise topology A from the previous section as follows:

Notice that we have added an instance d to topology A, and we have declared d private to A. We have also added a new connection to d in the connection graph C2.

Now suppose that we use the same definition of B given in the previous section. After import resolution, B will still be equivalent to the topology shown at the end of the last section: we have added an instance and a connection to A, but the instance is private and the connection goes from a private instance, so neither the instance nor the connection is imported into B.

Multiple imports are allowed. For example:

This has the obvious meaning: both topology B and topology C are imported into topology A, according to the rules described above.

Each topology may appear at most once in the import list. For example, this is incorrect:

In general, transitive imports are allowed. For example, topology A may import topology B, and topology B may import topology C. Resolution works bottom-up on the import graph: for example, first we resolve C, and then we resolve B, and then we resolve A.

Cycles in the import graph are not allowed. For example, if A imports B and B imports C and C imports A, you will get an error.

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 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:

To locate a port P in a file P.fpp, we write the following:

To locate an enum, we locate the type; the location of the enumerated constants are then implied:

As with include specifiers, the path name in a location specifier L is relative to the location of the file where L appears. For example, suppose the file b.fpp appears in the file system in some directory D. Suppose also that D has a subdirectory Constants, Constants contains a file a.fpp, and a.fpp defines the constant a. Then in b.fpp we could write this:

If, instead of residing in a subdirectory, a.fpp were located one directory above b.fpp in the file system, we could write this:

The definition name appearing after the keyword locate may be a qualified name. For example, suppose the file M.fpp contains the following:

Then in file b.fpp we could write this:

Optionally, we may enclose the location specifier in the module M, like this:

A location specifier written inside a module this way has its definition name implicitly qualified with the module name. For example, the name a appearing in the example above is automatically resolved to M.a.

Note that this rule is different than for other uses of definitions. For example, when using the constant M.a in an expression inside module M, you may spell the constant either a or M.a; but when referring to the same constant M.a in a location specifier inside module M, you must write a and not M.a. (If you wrote M.a, it would be incorrectly resolved to M.M.a.) The purpose of this rule is to facilitate dependency analysis, which occurs before the analyzer has complete information about definitions and their uses.

When you write a file that contains definitions and you include that file in another file, the location of each definition is the file where the definition is included, not the file where the definition appears. For example, suppose that file a.fppi contains the definition constant a = 0, 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.

To locate definitions, do the following:

For example, suppose the file Constants/a.fpp defines the constant a. Running

generates the location specifier

By default, the location path is relative to the current directory. To specify a different base directory, use the option -d. For example, running

generates the location specifier

Consider the case where you write a definition in one file and include that file in another file via an include specifier. For example, suppose file Constants.fpp looks like this:

Suppose b.fppi contains the definition constant b = 1. If you run find on this directory as described above and provide the output to fpp-locate-defs, then you will get the following output:

For purposes of dependency analysis, this is what you want. You want uses of b to depend on Constants.fpp (where the definition of b is included) rather than b.fpp (where the definition of b is stated).

When running a find command to find files containing definitions, you should exclude any files that are included in other files. If your main FPP files end with .fpp and your included FPP files end with .fppi, then running

will pick up just the main files.

To run fpp-depend, you pass it as input (1) files F that you want to analyze and (2) a superset of the location specifiers for the definitions used in that code. The tool extracts the location specifiers for the definitions used in F, resolves them to absolute path names (the dependencies of F), and writes the dependencies to standard output.

For example, suppose the file a.fpp contains the following definition:

Suppose the file b.fpp contains the following definition:

Suppose the file locations.fpp contains the following location specifiers:

And suppose the file c.fpp contains the following definition of c, which uses the definition of b but not the definition of a:

Then running fpp-depend locations.fpp c.fpp produces the output [path-prefix]/b.fpp. The dependency output contains absolute path names, which will vary from system to system. Here we represent the system-dependent part of the path as [path-prefix].

As usual with FPP tools, you can provide input as a set of files or on standard input. So the following is equivalent:

fpp-depend computes dependencies transitively. This means that if A depends on B and B depends on C, then A depends on C.

For example, suppose again that locations.fpp contains the following location specifiers:

Suppose the file a.fpp contains the following definition:

Suppose the file b.fpp contains the following definition:

And suppose that file c.fpp contains the following definition:

Notice that there is a direct dependency of c.fpp on b.fpp and a transitive dependency of c.fpp on a.fpp. The transitive dependency occurs because there is a direct dependency of c.fpp on b.fpp and a direct dependency of b.fpp on a.fpp.

Running fpp-depend on locations.fpp and c.fpp 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. Then the following facts are true:

In this case, by default, fpp-depend does the best that it can: it reports the dependency of c.fpp on b.fpp.

The philosophy behind fpp-depend is to be as permissive and enabling as possible. It doesn’t assume that something is wrong because a dependency is missing: for example, that dependency could be created later, as part of a code-generation step.

However, you may want to know about missing dependencies, either to issue a warning or error because something really is wrong, or to identify files to generate. To record missing dependencies, use the -m option. It takes as an argument the name of a file, and it writes missing dependencies (if any) to that file.

For example, the command

writes the missing dependency [path-prefix]/b.fpp to missing.txt in addition to writing the dependency [path-prefix]/b.fpp to standard output.

Suppose file a.fpp contains the include specifier include "b.fppi". Then there are two options for computing the dependencies of a.fpp:

Option 1 is what you want for assembling the input to FPP analysis and translation tools such as fpp-check. In this case, when analyzing a.fpp, the tool will resolve the include specifier and include the contents of b.fppi. So b.fppi should not be included as a separate input to the analysis.

On the other hand, suppose you are constructing a list of dependencies for a build system such as the F Prime CMake system. In this case, the build system doesn’t know anything about FPP include specifiers. However, it needs to know that a.fpp does depend on b.fppi in the sense that if b.fppi is modified, then a.fpp should be analyzed or translated again. So in this case we want option 2.

By default, fpp-depend provides option 1:

To get option 2, use the -i option to fpp-depend. It takes as an argument the name of a file, and it writes the included dependencies (if any) to that file.

In practice, you usually run fpp-depend with the -i file option enabled. Then option 1 corresponds to the output of the tool, and option 2 corresponds to the output plus the contents of file.

As discussed above, the standard output of fpp-depend reports transitive dependencies. This is ordinarily what you want (a) for computing the input to an FPP analysis tool and (b) for managing dependencies between files in a build. For example, suppose that a.fpp depends on b.fpp and b.fpp depends on c.fpp. When running analysis or code generation on a.fpp, you will need to import b.fpp and c.fpp (see the next section for an example). Further, if you have a build rule for translating a.fpp to XML, then you probably want to re-run that rule if c.fpp changes. Therefore you need to report a dependency of a.fpp on c.fpp.

However, suppose that your build system divides the FPP files into groups of files called build modules, and it manages dependencies between the modules. This is how the F Prime CMake system works. In this case, assuming there is no direct dependency from a.fpp to c.fpp, you may not want to report a dependency from a.fpp to c.fpp to the build system:

To compute direct dependencies, run fpp-depend with the option -d file. The tool will write a list of direct dependencies to file. Because direct dependencies are build dependencies, any included files will appear in the list. For this purpose, an included file is (a) any file included by an input file to fpp-depend; or (b) any file included by such a file, and so forth.

When setting up a build based on build modules, you will typically use fpp-depend as follows, for each module M in the build:

You can also use the -g option to identify generated files; we discuss this option below. Note that we do not use the -i option to fpp-depend, because the relevant 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. For example, use of a guarded input port requires that an operating system provides a mutex lock.

To report framework dependencies, run fpp-depend with the option -f file, where file is the name of an output file. The currently recognized framework dependencies are as follows:

Each dependency corresponds to a build module (i.e., a statically compiled library) of the F Prime framework. fpp-depend writes the dependencies in the order that they must be provided to the linker.

A relative path is a path that does not start with a slash and is relative to the current directory path, which is set by the environment in which an FPP tool is run. For example, the command sequence

sets the current directory path to /home/user/dir and then runs fpp-check file.fpp. In this case, the relative path file.fpp is resolved to /home/user/dir/file.fpp. An absolute path is a path that starts with a slash and specifies a complete path from the root of the file system, e.g., /home/user/dir/file.fpp.

Because FPP is implemented in Scala, relative paths are resolved by the Java Virtual Machine (JVM). When the current directory path contains a symbolic link, this resolution may not work in the way that you expect. For example, suppose the following:

Suppose that D contains a file file.fpp, and that the current directory path is D. In this case, when you run an FPP tool with file.fpp as input, any symbols defined in file.fpp will have location D /file.fpp, as expected.

Now suppose that the current directory path is S. In this case, when you run an FPP tool with file.fpp as input, the symbols defined in file.fpp again have location D /file.fpp, when you might expect them to have location S /file.fpp. This is because the JVM resolves all symbolic links before computing relative path names.

This behavior can cause problems when using the -p (path prefix) option with FPP code generation tools, as described in the section on analyzing and translating models. 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 s is defined. If paths contain names that are aliased via symbolic links or hard links, then this may not be true: for example, P₁ and P₂ may be syntactically different absolute paths that represent the same physical location in the file system. In this case it may be possible for the tools to associate two different locations with the same FPP symbol definition.

You must ensure that this doesn’t happen. If you present the same file F to the FPP tools several times, for example to locate definitions and to compute dependencies, you must ensure that the path describing F is the same each time, after resolving relative paths as described above.

fpp-to-cpp extracts constant definitions from the source files F. It generates files FppConstantsAc.hpp and FppConstantsAc.cpp containing C++ translations of the constants. By including and/or linking against these files, you can use constants defined in the FPP model in your FSW implementation code.

To keep things simple, only numeric, string, and Boolean constants are translated; struct and array constants are ignored. For example, the following constant is not translated, because it is an array:

To translate array constants, you must expand them to values that are translated, like this:

Constants are translated as follows:

As an example, try this:

You should see files FppConstantsAc.hpp and FppConstantsAc.cpp in the current directory. Examine them to confirm your understanding of how the translation works. Notice how the FPP annotations are translated to comments. (We also remarked on this in the section on writing annotations.)

Constants defined inside components: As noted in the section on defining components, when you define a constant c inside a component C, the name of the corresponding constant in the generated C++ code is C_c. As an example, run the following code through fpp-to-cpp and examine the results:

Generated header paths: The option -p path-prefixes removes the longest of one or more path prefixes from any generated header paths (for example, the path to FppConstants.hpp that is included in FppConstants.cpp). To specify multiple prefixes, separate them with commas (and no spaces). This is similar to the -p option for fpp-to-xml.

The include guard prefix: By default, the include guard for FppConstantsAc.hpp is guard-prefix _FppConstantsAc_HPP, where guard-prefix is the absolute path of the current directory, after replacing non-identifier characters with underscores. For example, if the current directory is /home/user, then the guard prefix is _home_user, and the include guard is _home_user_FppConstantsAc_HPP.

The -p option, if present, is applied to the guard prefix. For example, if you run fpp-to-cpp -p $PWD …​ then the guard prefix will be empty. In this case, the guard is FppConstantsAc_HPP.

If you wish to use a different prefix entirely, use the option -g guard-prefix. For example, if you run fpp-to-cpp -g Commands …​, then the include guard will be Commands_FppConstantsAc_HPP.

More options: The following additional options are available when running fpp-to-cpp:

To generate code for type, port, state machine, and component definitions, you run fpp-to-cpp in the same way as for constant definitions, with one exception: the translator ignores the -g option, because the include guard comes from the qualified name of the definition. For example, a component whose qualified name in FPP is A.B.C uses the name A_B_CComponentAc_HPP in its include guard.

Once you generate C++ code for these definitions, you can use it to write a flight software implementation. The F User Manual explains how to do this.

For more information about the generated code for data products, for state machines, and for state machine instances, see the F Prime design documentation.

fpp-to-cpp has options -t and -u for generating component “templates” or partial implementations and for generating unit test code. Here we cover the mechanics of using these options. For more information on implementing and testing components in F Prime, see the F Prime User Manual.

Generating implementation templates: When you run fpp-to-cpp with option -t and without option -u, it generates a partial implementation for each component definition C in the input. The generated files are called C .template.hpp and C .template.cpp. You can fill in the blanks in these files to provide the concrete implementation of C.

Generating unit test harness code: When you run fpp-to-cpp with option -u and without option -t, it generates support code for testing each component definition C in the input. The unit test support code resides in the following files: