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

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.

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’s Guide.

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’s Guide.

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’s Guide.

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’s Guide.

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’s Guide.

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’s Guide.

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’s Guide.

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’s Guide.

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:

fpp-to-cpp also extracts topology definitions from the source files. For each topology T defined in the source files, fpp-to-cpp writes files T TopologyAc.hpp and T TopologyAc.cpp. These files define two public functions: setup for setting up the topology, and teardown, for tearing down the topology. The function definitions come from the definition of T and from the init specifiers for the component instances used in T. You can call these functions from a handwritten main function. We will explain how to write this main function in the section on implementing deployments.

As an example, you can do the following:

You can examine the files RefTopologyAc.hpp and RefTopologyAc.cpp in the F Prime repository. Currently these files are checked in at Ref/Top. Once we have integrated FPP with CMake, these files will be auto-generated by CMake and will be located at Ref/build-fprime-automatic-native/F-Prime/Ref/Top.

Options: When translating topologies, the -d, -n, and -p options work in the same way as for translating constant definitions. The -g option is ignored, because the include guard prefix comes from the name of the topology.

C++ code generation for types, ports, and components works similarly to the corresponding code generation from XML. The F Prime User’s Guide describes how to use this generated code to write flight software implementations.

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’s Guide.

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:

Generating unit test templates: When you run fpp-to-cpp with both the -u and the -t options, it generates a template or partial implementation of the unit tests for each component C in the input. The generated code consists of the following files:

Unit test auto helpers: When running fpp-to-cpp with the -u option, you can also specify the -a or unit test auto helpers option. This option moves the generation of the file C TesterHelpers.cpp from the unit test template code to the unit test harness code. Specifically:

The -a option supports a feature of the F Prime CMake build system called UT_AUTO_HELPERS. With this feature enabled, you don’t have to manage the file C TesterHelpers.cpp as part of your unit test source files; the build system does it for you.

Like fpp-check, fpp-filenames reads the files provided as command-line arguments if there are any; otherwise it reads from standard input. The FPP source presented to fpp-filenames need not be a complete model (i.e., it may contain undefined symbols). When run with no options, tool parses the FPP source that you give it. It identifies all definitions in the source that would cause XML files to be generated when running fpp-to-xml or would cause C++ files to be generated when running fpp-to-cpp. Then it writes the names of those files to standard output.

For example:

You can run fpp-filenames with the -u option, with the -t option, or with both options. In these cases fpp-filenames writes out the names of the files that would be generated by running fpp-to-cpp with the corresponding options. For example:

You can also also run fpp-filenames with the -a option. Again the results correspond to running fpp-to-cpp with this option. For example:

Alternatively, you can use fpp-depend to write out the names of generated files during dependency analysis. The output is the same as for fpp-filenames, but this way you can run one tool (fpp-depend) instead of two (fpp-depend and fpp-filenames). Running one tool may help your build go faster.

fpp-depend provides the following options:

-a: Enable unit test auto helpers.

-g file: Write the names of the generated autocode files to the file file.

-u file: Write the names of the unit test support code files to file.

For example:

fpp-depend does not have an option for writing out the names of implementation template files, since those file names are not needed during dependency analysis.

As discussed in the section on generating C++ topology definitions, when you translate an FPP topology T to C++, the result goes into files T TopologyAc.hpp and T TopologyAc.cpp. The generated file T TopologyAc.hpp includes a file T TopologyDefs.hpp. The purpose of this file inclusion is as follows:

T TopologyDefs.hpp must be located in the same directory where the topology T is defined. When writing the file T TopologyDefs.hpp, you should follow the description given below.

Topology state: T TopologyDefs.hpp must define a type TopologyState in the C++ namespace corresponding to the FPP module where the topology T is defined. For example, in SystemReference/Top/topology.fpp in the F Prime system reference deployment, the FPP topology SystemReference is defined in the FPP module SystemReference, and so in SystemReference/Top/SystemReferenceTopologyDefs.hpp, the type TopologyState is defined in the namespace SystemReference.

TopologyState may be any type. Usually it is a struct or class. The C++ code generated by FPP passes a value state of type TopologyState into each of the functions for setting up and tearing down topologies. You can read this value in the code associated with your init specifiers.

In the F Prime system reference example, TopologyState is a struct with two member variables: a C-style string hostName that stores a host name and a U32 value portNumber that stores a port number. The main function defined in Main.cpp parses the command-line arguments to the application, uses the result to create an object state of type TopologyState, and passes the state object into the functions for setting up and tearing down the topology. The startTasks phase for the comDriver instance uses the state object in the following way:

In this code snippet, the expressions state.hostName and state.portNumber refer to the hostName and portNumber member variables of the state object passed in from the main function.

The state object is passed in to the setup and teardown functions via const reference. Therefore, you may read, but not write, the state object in the code associated with the init specifiers.

Health ping entries: If your topology uses an instance of the standard component Svc::Health for monitoring the health of components with threads, then T TopologyDefs.hpp must define the health ping entries used by the health component instance. The health ping entries specify the time in seconds to wait for the receipt of a health ping before declaring a timeout. For each component being monitored, there are two timeout intervals: a warning interval and a fatal interval. If the warning interval passes without a health ping, then a warning event occurs. If the fatal interval passes without a health ping, then a fatal event occurs.

You must specify the health ping entries in the namespace corresponding to the FPP module where T is defined. To specify the health ping entries, you do the following:

For example, here are the health ping entries from SystemReference/Top/SystemReferenceTopologyDefs.hpp in the F Prime system reference repository:

Other definitions: You can put any compile-time definitions you wish into T TopologyAc.hpp If you need link-time definitions (e.g., to declare variables with storage), you can put them in T TopologyAc.cpp, but this is not required.

For example, SystemReference/Top/SystemReferenceTopologyAc.hpp declares a variable SystemReference::Allocation::mallocator of type Fw::MallocAllocator. It provides an allocator used in the setup and teardown of several component instances. The corresponding link-time symbol is defined in SystemReferenceTopologyDefs.cpp.

You must write a main function that performs application-specific and system-specific tasks such as parsing command-line arguments, handling signals, and returning a numeric code to the system on exit. Your main code can use the following public interface provided by T TopologyAc.hpp:

These functions reside in the C++ namespace corresponding to the FPP module where the topology T is defined.

On Linux, a typical main function might work this way:

For an example like this, see SystemReference/Top/Main.cpp in the F Prime system reference repository.

The header file T TopologyAc.hpp declares several public symbols that you can use when writing your main function.

Instance variables: Each component instance used in the topology is declared as an extern variable, so you can refer to any component instance in the main function. For example, the main function in the SystemReference topology calls the method callIsr of the blockDrv (block driver) component instance, in order to simulate an interrupt service routine (ISR) call triggered by a hardware interrupt.

Helper functions: The auto-generated setup function calls the following auto-generated helper functions:

The auto-generated teardown function calls the following auto-generated helper functions:

The helper functions are declared as public symbols in T TopologyAc.hpp, so if you wish, you may write your own versions of setup and teardown that call these functions directly. The FPP modeling is designed so that you don’t have to do this; you can put any custom C++ code for setup or teardown into init specifiers and let the FPP translator generate complete setup and teardown functions that you simply call, as described above. Using init specifiers generally produces cleaner integration between the model and the C++ code: you write the custom C++ code once, any topology T that uses an instance I will pick up the custom C++ code for I, and the FPP translator will automatically put the code for I into the correct place in T TopologyAc.cpp. However, if you wish to write the custom code directly into your main function, you may.