The F Prime Prime (FPP) Language Specification, Unreleased, after v2.0.2

The following are reserved words in FPP. They may not be used as identifiers, except when preceded by the $ character, as discussed below.

The following sequences of characters are symbol tokens in FPP:

Definition: An identifier is an unqualified name consisting of one or more characters. The first character must be a letter or an underscore. Characters after the first character may be letters, digits, and underscores.

For example:

Escaped keywords: Any identifier may be preceded by the character $, with no intervening space. An identifier $ I has the same meaning as I, except that if I is a reserved word, then I is scanned as an identifier and not as a reserved word.

For example:

An end-of-line token is a sequence of one or more newlines. A newline (or line break) is the NL character (ASCII code 0x0A), optionally preceded by a CR character (ASCII code 0x0D). End-of-line tokens separate the elements of element sequences.

The lexer ignores comments. Specifically:

Apart from end-of-line tokens, the lexer treats whitespace as follows:

The character \, when appearing before a newline, suppresses the newline. Both the \ and the following newline are ignored, and no end-of-line token, is created. For example, this

is equivalent to this:

Note that \ is required in this case. For example, the following is not syntactically correct:

The newline indicates the end of an element sequence, but constant a is not a valid element sequence.

The following symbols consume sequences of newlines that follow them, without creating an end-of-line token:

For example, the following code is legal:

It is equivalent to this code:

The newline after the { symbol is consumed by the symbol. The newline after the constant definition is consumed by the element sequence member.

The following code is also legal, because the newline is consumed by the = symbol:

Similarly, the following code is legal, because the newline is consumed by the + symbol:

To simplify parsing, the lexer may collapse a sequence of one or more end-of-line tokens into a single token, or into no token, if the operation does not change the meaning of the result according to the parse rules. For example, the lexer may treat this code

as if it were this

or this

According to the rules for parsing element sequences, all three code sections are equivalent.

An abstract type definition associates a name with a type without specifying the type. In generated code, the type is specified externally (e.g., as a C++ class).

An array definition defines a new array type and associates a name with it.

A component definition defines an F Prime component. A component is a unit of function in the F Prime framework. Component instances communicate with each other across ports.

A component instance definition defines an instance of a component that you can refer to in a topology definition.

A constant definition associates a name with a compile-time constant value. You can use the name in place of the value elsewhere in the model.

An enum definition does two things:

An enumerated constant definition is an element of an enum definition. Like a constant definition, it associates a value with a named constant. It also establishes that the constant is one of the values of the type defined in the enum definition.

A module definition provides a named scope that encloses and qualifies other definitions, including other module definitions. It is similar to a namespace in C++ or a package in Java or Scala.

An port definition defines an F Prime port. A port is the endpoint of a connection between F Prime components.

A struct definition defines a new structure type and associates a name with it.

A topology definition defines an F Prime topology, that is, a set of component instances and the connections between their ports. The connections are divided into named connection graphs. The different graphs capture different aspects of FSW function, such as commanding and telemetry.

One topology can be imported into another one. The connections are merged graph by graph.

A command specifier specifies a command as part of a component definition.

A component instance specifier specifies that a component instance is part of a topology.

A connection graph specifier specifies one or more connection graphs as part of a topology definition. A connection graph is a named set of connections. A connection connects an output port instance of one component instance to an input port instance of another.

A container specifier specifies a data product container as part of a component definition. Containers are units of data that can be downlinked and then deleted. They hold data product records.

An event specifier specifies an event report as part of a component definition.

An include specifier specifies that a file should be included in a translation unit.

An init specifier associates some code with a component instance. Usually this is initialization code, hence the name. It may also serve another purpose (e.g., teardown).

An internal port specifier specifies a single-use port for use in handlers of the enclosing component. A component can use an internal port to send a message to itself.

A location specifier specifies the location of a definition.

A parameter specifier specifies a parameter as part of a component definition.

A port instance specifier specifies an instantiated port as part of a component definition.

A port matching specifier is part of a component definition. It specifies that when the component is instantiated and connected into a topology, the corresponding port numbers of two of its port instances should match. For example, a port matching specifier could specify that for a health monitoring component, any component connected to its ping output port at port number n should also be connected to its ping input port at the same port number n.

A record specifier specifies a data product record as part of a component definition. A record is a unit of data that is stored in a container.

A telemetry channel definition defines a telemetry channel as part of a component definition.

A topology import specifier imports one topology into another one.

qual-ident . identifier

For each port instance identifier Q . P:

In the first example, a names a component instance, and b names a port instance. In the second example, A.b names a component instance, and c names a port instance.

Primitive integer type names are the names of the primitive integer types. There are two kinds of primitive integer types: unsigned integer types and signed integer types.

The floating-point type names are F32 and F64. These refer to the types of IEEE floating-point values of width 32 and 64 bits, respectively.

The type name bool represents the type of the two Boolean values true and false.

A string type name consists of the keyword string optionally followed by the keyword size and an expression. For example:

The optional expression following the keyword size is called the size expression of the string type name. If present, it must have a numeric type, and it must evaluate to a value in the range [0,2³¹) after conversion to Integer. The size expression specifies the maximum length of a string value represented by the type. If the size expression is not present, then the translator uses a default maximum string length.

A qualified identifier type name is a qualified identifier that refers to an abstract type definition, array definition, enum definition, or struct definition via the rules for name scoping. It names the type defined in the definition to which it refers.

For example:

FPP includes the following arithmetic expressions:

Each subexpression of an arithmetic expression must have numeric type. Evaluation is by either standard integer arithmetic or standard floating-point arithmetic, depending on the type of the expression.

Example:

An array expression is an expression that represents an array value.

A Boolean literal expression is one of the values true and false.

A dot expression is a use that refers to a constant definition or enumerated constant definition.

A floating-point literal expression is a C-style representation of an IEEE floating-point number.

Examples:

An identifier expression is an identifier that refers to a constant definition or enumerated constant definition, according to the rules for resolving identifiers.

Example:

An integer literal expression is one of the following:

An integer literal value \$v\$ is represented in the model as an integer of arbitrary width. During code generation, the width is narrowed (if necessary) to some machine width less than or equal to 64 bits.

Examples:

A parenthesis expression is an expression surrounded by parentheses in order to group subexpressions and to force evaluation order.

A string literal expression is a single-line string literal or a multiline string literal. In this section

An struct expression is an expression that represents a struct value.

Ambiguity in parsing expressions is resolved with the following precedence table. Expressions appearing earlier in the table have higher precedence. For example, -a.b is parsed as -(a.b) and not (-a).b. Where necessary, each element in the ordering provides an associativity for resolving expressions with equal precedence.

Formal parameters have the following syntax:

[ ref ] identifier : type-name

If present, the keyword ref specifies that the value bound to the formal parameter is to be passed by reference when it is used in a synchronous port invocation.

The identifier is the name of the formal parameter. No two parameters in the same formal parameter list may have the same name.

The type name specifies the type T of the formal parameter P.

A comment is model text that is ignored by the translator. It provides information to human readers of the source model.

Comments begin with the character # and go to the end of the line. For example:

To write a multiline comment, precede each line with #:

An annotation is similar to a comment, but it is attached to a syntactic element of a model, and it is preserved during analysis and translation. The precise use of annotations depends on the translator. A typical use is to include annotations as comments in generated code.

A translation unit forms part of a model at the top level. Translation units usually correspond to source files of a program. However, translation units may be specified in other ways, e.g., on standard input.

A model is a collection of one or more translation units. A model is presented to one or more analyzers or translators for analysis or translation. How this is done depends on the analyzer or translator. Typically, you ask a translator to read a single translation unit from standard input and/or to read one or more translation units stored in files, one unit per file.

Example:

Translation units 1-3 in the previous section, taken together, form a single model. That model is equivalent to the following single translation unit:

According to the semantics of module definitions, this is also equivalent:

Note that translation unit 3 alone is not a valid model, because it uses free symbols defined in the other translation units. Similarly, the translation unit 3 together with just translation unit 1 or translation unit 2 is not a valid model.

Every syntactic element E in a source model has an associated location L. The location is used when resolving location specifiers and include specifiers during analysis.

A qualified identifier is one of the following:

Examples:

Every definition D appearing in an FPP model has a unique qualified name. The qualified name is a qualified identifier formed as follows:

For example:

The qualified names of definitions and reside in the following name groups:

Definitions reside in name groups as follows:

Notice that elements with scopes reside in the name groups of items that they may enclose. For example, enums reside in the value name group because they enclose constant definitions.

The following rules govern the resolution of identifiers, i.e., associating identifiers with definitions:

Example:

S refers to the value name group.

The following rules govern the resolution of qualified identifiers, i.e., associating qualified identifiers with definitions:

Example:

A use is a qualified identifier that refers to a definition according to the scoping rules for names.

A use is a qualifying use if it qualifies another use. For example, in the following code

If a use u is not a qualifying use, then we say it is a non-qualifying use.

The set of definitions and non-qualifying uses in an FPP model induces a directed graph called the use-def graph. In this graph,

For example, in the following code, the use-def graph has two nodes a and b and one edge b \$rarr\$ a.

In a legal FPP model, the use-def graph must be acyclic. For example, this model is illegal:

This model is also illegal:

This model is legal:

The use M appears inside the definition of M. However, it is a qualifying use.

So long as the use-def graph is acyclic, there is no constraint either on the ordering of definitions and uses within a translation unit, or on the distribution of definitions and uses among translation units. For example, if the definition constant c = 0 appears anywhere in any translation unit of a model M, then the use of c as a constant value of type Integer is legal anywhere in any translation unit of M. In particular, this model is legal:

The model consisting of two translation units

and

is also legal, and the order in which the units are presented to the translator does not matter.

The primitive integer types correspond to the primitive integer type names and are written in the same way, e.g., U32.

The floating-point types correspond to the floating-point type names and are written in the same way, e.g., F64.

The primitive integer types together with the floating-point types are called the primitive numeric types.

The Boolean type corresponds to the Boolean type name. It is written bool.

Together, the primitive numeric types and the Boolean type are called the primitive types.

The string types correspond to the string type names. A string type is written string or string size n, where n is an integer value in the range [1,2^31-1]. There is one string type string and one string type string n for each legal value of n.

An array type is a type associated with an array definition. There is one array type per array definition. Each array type is computed after resolving constants, so an array type has a constant integer value for its size. An array type is written using its unique qualified name.

An enum type is a type associated with an enum definition. There is one enum type per enum definition. An enum type is written using its unique qualified name.

A struct type is a type associated with a struct definition. There is one struct type per struct definition. A struct type is written using its unique qualified name.

An abstract type is a type associated with an abstract type definition. There is is one abstract type per abstract type definition. An abstract type is written using its unique qualified name.

Internal types do not have syntactic names in FPP source models. The compiler assigns these types to expressions during type checking.

A type has numeric members if it is one of the following:

Every type T with a syntactic name in FPP has an associated default value. In generated C++ code, this is the value that is used to initialize a variable of type T when no other initializer is specified. Default values are important, because they ensure that in generated code, every variable is initialized when it is created.

To type an integer literal expression, the semantic analyzer does the following:

Examples:

The type of a floating-point literal expression is F64.

The type of a boolean literal expression is bool.

The type of a string literal expression is string.

To type an identifier expression \$e\$, the semantic analyzer resolves the identifier to a definition and uses the type given in the definition.

Example:

To type a dot expression \$e\$ .x, the semantic analyzer does the following:

Example:

To type an array expression [ \$e_1\$ , \$...\$ , \$e_n\$ ], the semantic analyzer does the following:

Examples:

To type a struct expression { \$m_1\$ = \$e_1\$ , \$...\$ , \$m_n\$ = \$e_n\$ }, the semantic analyzer does the following:

Examples:

To type a unary negation expression - \$e\$, the semantic analyzer does the following:

Examples:

To type a binary arithmetic expression \$e_1\$ op \$e_2\$, the semantic analyzer does the following:

Examples:

To type a parenthesis expression ( \$e\$ ), the semantic analyzer does the following:

Examples:

We say that types \$T_1\$ and \$T_2\$ are identical if one of the following holds:

We say that a type \$T_1\$ may be converted to another type \$T_2\$ if every value represented by type \$T_1\$ can be converted into a value of type \$T_2\$.

Here are the rules for type conversion:

A primitive integer value is an ordinary (mathematical) integer value together with a primitive integer type. Formally, the set of primitive integer values is the disjoint union over the integer types of the values represented by each type:

We represent a primitive integer value as an expression followed by a colon and a type. For example, we write the value 1 at type U32 as 1: U32. The value 1: U32 is distinct from the value 1: U8.

An integer value is an ordinary (mathematical) integer value. It has type Integer. We represent an integer value as an integer number, with no explicit type. For example, 1 is an integer value.

A floating-point value is an IEEE floating-point value of 4- or 8-byte width. Formally, the set of floating-point values is the disjoint union over the types F32 and F64 of the values represented by each type:

We write a floating-point values analogously to primitive integer values. For example, we write the value 1.0 at type F32 as 1.0: F32.

A Boolean value is one of the values true and false. Its type is bool.

A string value is a sequence of characters that can be represented as a string literal expression. It is written in the same way as a string literal expression, e.g., "abc". Its type is string.

An abstract type value is a value associated with an abstract type. There is one value associated with each abstract type \$T\$. We write the value value of type \$T\$.

An anonymous array value is a value associated with an anonymous array type. We write an anonymous array value similarly to an array expression: an anonymous array value has the form [ \$v_1\$ , \$...\$ , \$v_n\$ ], where for each \$i in [1,n\$], \$v_i\$ is a value of type \$T\$ for some \$T\$. The type of the value is [ \$n\$ ] \$T\$.

An array value is a value associated with an array type. We write an array value like an anonymous array value, except that the value is annotated with an array type.

An array value has the form [ \$v_1\$ , \$...\$ , \$v_n\$ ] : \$Q\$, where

The type of the value is \$Q\$.

An enumeration value is a value associated with an enumerated constant definition. It is a pair consisting of the name and the integer value specified in the enumerated constant definition. Its type is the type associated with the enum definition in which the enumerated constant definition appears.

An anonymous struct value is a value associated with an anonymous struct type. We write an anonymous struct value \$v\$ similarly to a struct expression: a struct value has the form { \$m_1\$ = \$v_1\$ , \$...\$ , \$m_n\$ = \$v_n\$ }, where for each \$i in [1,n\$], \$v_i\$ is a value of type \$T_i\$. The type of \$v\$ is { \$m_1\$ : \$T_1\$ , \$...\$ , \$m_n\$ : \$T_n\$ }.

A struct value is a value associated with a struct type. We write a struct value similarly to an anonymous struct value, except that we annotate the value with a struct type: a struct value has the form { \$m_1\$ : \$v_1\$ , \$...\$ , \$m_n\$ : \$v_n\$ } : \$Q\$, where

All the members must be explicitly assigned values.

Every value v whose type has a syntactic representation in FPP has a serialized size. This is the number of bytes required to represent v in the standard F Prime serialized format. The serialized size s of a value v depends on the type T of v:

Evaluation of expressions occurs as stated in the expression descriptions. Evaluation of integer expressions occurs at type Integer, using enough bits to represent the result without overflow. Evaluation of floating-point expressions occurs using 64-bit floating-point arithmetic.

The following rules govern the conversion of a value \$v_1\$ of type \$T_1\$ to a value \$v_2\$ of type \$T_2\$.

Analysis is the process of checking a source model. It usually involves the following steps:

An analysis tool is a tool that reads in and analyzes FPP source files, but does not generate any code. Source files for analysis are provided in one of two ways:

For example, the command analyze file1.fpp file2.fpp says to read in the translation units file1.fpp and file2.fpp and perform analysis on the model consisting of these two translation units. The command cat file1.fpp file2.fpp | analyze is functionally equivalent.

Translation is the process of performing analysis and generating code.

Translation usually involves the following steps:

FPP is intended to support a variety of translation strategies. For example, we need to generate (1) C++ code for FSW and (2) XML, Python, or other code to export to ground tools.

A translation tool is a tool that translates FPP source files. A translation tool typically accepts the following two kinds of input:

For example, when translating a component C, a tool may read in files containing the definitions of the ports used in C, but not translate those files.

Source files for translation are provided as for analysis tools. Imported source files are specified as arguments to a -i flag.

For example, the command translate -i file1.fpp,file2.fpp file3.fpp says to import file1.fpp and file2.fpp and translate file3.fpp. The command translate -i file1.fpp,file2.fpp < file3.fpp is functionally equivalent.