From 57a4937d2cc189eeccbf6afaf1b3cc5cf84d3beb Mon Sep 17 00:00:00 2001 From: jwest115 Date: Tue, 25 Jun 2024 11:21:50 -0700 Subject: [PATCH 1/7] updated XML and GDS limitations --- docs/fpp-users-guide.html | 75 --------------------------------------- 1 file changed, 75 deletions(-) diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 1c7463317..30a92c6f0 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -1942,32 +1942,6 @@

5. Defining Modules

@ This is module M
 module M {
   constant a = 0
-}
- - -
-

XML limitation: The F Prime XML format supports -only one level of C++ namespaces. -Therefore nested modules are not translated properly to C++. -As a workaround, you can use an underscore prefix. -For example, instead of writing

-
-
-
-
module A {
-  module B {
-
-  }
-}
-
-
-
-

you can write

-
-
-
-
module A_B {
-
 }
@@ -2576,13 +2550,6 @@

6.2.4. Member Arra

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

-
-

GDS limitation: The F Prime GDS does not properly handle -member arrays. -Therefore, if you plan to use the F Prime GDS, then you should avoid -using a struct type with a member array in the flight-ground interface (i.e., -commands, events, telemetry, and parameters).

-

6.2.5. Member Format Strings

@@ -2997,15 +2964,6 @@

7.4. The Representation Type

U8 value in C++.

-
-

GDS limitation: -The F Prime GDS currently assumes that all enums use the default representation -size of I32. -Therefore, if you plan to use the F Prime GDS, then -you should not use any enum with a specified representation -type other than I32 in the flight-ground interface (i.e., commands, events, telemetry, -and parameters).

-

7.5. The Default Value

@@ -5685,11 +5643,6 @@

9.7.5. Limits

each of whose members satisfies condition (1) or condition (2).

-
-

XML limitation: The F Prime XML representation does -not allow limits for telemetry channels -of array or struct type.

-
@@ -6398,34 +6351,6 @@

9.10. Constants and Types

The name scoping mechanism emphasizes the hierarchical relationship and prevents name clashes.

-
-

XML limitation: In most cases, a qualified name such as Switch.State -in FPP becomes a qualified name such as Switch::State when translating -to C++. -However, the F Prime XML format does not support the definition -of constants and types as members of C++ components. -Therefore, when translating the previous example through XML to C++, -the following occurs:

-
-
-
    -
  1. -

    The component Switch becomes an auto-generated C++ class -SwitchComponentBase.

    -
    2. -
  2. -

    The type State becomes a C++ class Switch_State.

    -
    3. -
-
-
-

Similarly, the FPP constant SerialSplitter.splitFactor -becomes a C++ constant SerialSplitter_SplitFactor. -We will have more to say about this issue in the sections on -generating XML -and -generating C++.

-

9.11. Include Specifiers

From ac02e9a99a789e6f28df5d90419b2519f7715c48 Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 25 Jun 2024 13:01:46 -0700 Subject: [PATCH 2/7] Revise User's Guide --- docs/fpp-spec.html | 2 +- docs/fpp-users-guide.html | 65 +++++++++++-------- docs/index.html | 2 +- .../Analyzing-and-Translating-Models.adoc | 11 ++-- docs/users-guide/Defining-Components.adoc | 8 +-- docs/users-guide/Defining-Enums.adoc | 8 --- docs/users-guide/Defining-Modules.adoc | 25 ------- docs/users-guide/Defining-Topologies.adoc | 2 +- docs/users-guide/Defining-Types.adoc | 6 -- docs/users-guide/Introduction.adoc | 17 +---- 10 files changed, 48 insertions(+), 98 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index 844ebb074..ed5e4aa3a 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -8551,7 +8551,7 @@

20.4. Translation Tools

diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 30a92c6f0..305cf71cb 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -739,7 +739,7 @@

1. Introduction

  • To generate code in the various languages that F Prime uses, e.g., -C++, Python, XML. +C++, JSON, and XML. In this document, we will call these languages the target languages.

    • @@ -766,23 +766,6 @@

    1. Introduction

    We recommend that you read this document before consulting that one.

    -

    XML limitations: -As of this writing, F Prime still uses an older XML format, e.g., -to support the Ground Data System (GDS). -Some features of FPP are not supported in the XML representation. -Where a feature is not supported in XML, we will call out this fact in a -note marked XML limitation. -As we phase out the XML code generation, we will phase in support -for all the features described here.

    -
    -
    -

    GDS limitations: -It is currently possible to construct FPP models that are not -fully supported by the F Prime Ground Data System (GDS). -Where an FPP feature is not supported in the GDS, we will call out this -fact in a note marked GDS limitation.

    -
    -

    Overview: The rest of this document proceeds as follows. Section 2 explains how to get up and running with FPP. Sections 3 through 11 describe the elements of an FPP @@ -6351,6 +6334,34 @@

    9.10. Constants and Types

    The name scoping mechanism emphasizes the hierarchical relationship and prevents name clashes.

    +
    +

    In most cases, a qualified name such as Switch.State +in FPP becomes a qualified name such as Switch::State when translating +to C++. +However, the F Prime XML format does not support the definition +of constants and types as members of C++ components. +Therefore, when translating the previous example to C++, +the following occurs:

    +
    +
    +
      +
    1. +

      The component Switch becomes an auto-generated C++ class +SwitchComponentBase.

      +
      2. +
    2. +

      The type State becomes a C++ class Switch_State.

      +
      3. +
    +
    +
    +

    Similarly, the FPP constant SerialSplitter.splitFactor +becomes a C++ constant SerialSplitter_SplitFactor. +We will have more to say about this issue in the sections on +generating XML +and +generating C++.

    +

    9.11. Include Specifiers

    @@ -7458,7 +7469,7 @@

    11.1. A Simple Example

    As shown, to write an instance specifier, you write the keyword instance and the name of a component instance definition. -In general the name may be a qualified name such as A.B +In general the name may be a qualified name such as A.B. if the instance is defined inside a module; in this simple example it is not. @@ -9947,7 +9958,11 @@

    13.1. Checking Models<

    13.2. Generating XML

    -

    This section describes how to generate XML from FPP.

    +

    The use of XML in F Prime is being phased out in favor of generating +JSON and directly generating C++. +However, the F Prime XML representation is still used, e.g., in +for specifying the layout of telemetry packets. +This section describes how to generate XML from FPP.

    XML file names: The table XML File Names shows how FPP definitions are @@ -10254,12 +10269,6 @@

    13.2. Generating XMLfpp-check.

    -
    -

    XML limitations: The XML translation has several -limitations. -For more information, see the text marked XML limitations elsewhere -in this manual.

    -

    13.3. Generating C Plus Plus

    @@ -10536,7 +10545,7 @@

    fpp-to-xml.

  • -

    -n file : Write the names of the generated XML files +

    -n file : Write the names of the generated C++ files to file. This is similar to the -n option for fpp-to-xml.

    @@ -12285,7 +12294,7 @@

    -Last updated 2024-06-20 11:08:28 -0700 +Last updated 2024-06-25 11:58:28 -0700

    • diff --git a/docs/index.html b/docs/index.html index d0a1300ac..54e086c37 100644 --- a/docs/index.html +++ b/docs/index.html @@ -463,7 +463,7 @@

    F Prime Prime (FPP)

    diff --git a/docs/users-guide/Analyzing-and-Translating-Models.adoc b/docs/users-guide/Analyzing-and-Translating-Models.adoc index ae3d65b54..fcd527176 100644 --- a/docs/users-guide/Analyzing-and-Translating-Models.adoc +++ b/docs/users-guide/Analyzing-and-Translating-Models.adoc @@ -138,6 +138,10 @@ even though `c.Out` has two ports and only one of them is connected. === Generating XML +The use of XML in F Prime is being phased out in favor of generating +JSON and directly generating {cpp}. +However, the F Prime XML representation is still used, e.g., in +for specifying the layout of telemetry packets. This section describes how to generate XML from FPP. *XML file names:* The table <> shows how FPP definitions are @@ -348,11 +352,6 @@ an automatic default of 80. you can provide FPP source on standard input, as described for <>. -*XML limitations:* The XML translation has several -limitations. -For more information, see the text marked *XML limitations* elsewhere -in this manual. - === Generating C Plus Plus This section describes how to generate {cpp} from FPP. @@ -542,7 +541,7 @@ the output directory for writing files. This is similar to the `-d` option for <>. -* `-n` _file_ : Write the names of the generated XML files +* `-n` _file_ : Write the names of the generated {cpp} files to _file_. This is similar to the `-n` option for <>. diff --git a/docs/users-guide/Defining-Components.adoc b/docs/users-guide/Defining-Components.adoc index 26a2f796a..eb55a8bbc 100644 --- a/docs/users-guide/Defining-Components.adoc +++ b/docs/users-guide/Defining-Components.adoc @@ -1850,10 +1850,6 @@ has a numeric type; or (3) an array or struct type each of whose members satisfies condition (1) or condition (2). -*XML limitation:* The F Prime XML representation does -not allow limits for telemetry channels -of array or struct type. - === Parameters When defining an F Prime component, you may specify one or more @@ -2508,12 +2504,12 @@ when the definition logically belongs to the component. The name scoping mechanism emphasizes the hierarchical relationship and prevents name clashes. -*XML limitation:* In most cases, a qualified name such as `Switch.State` +In most cases, a qualified name such as `Switch.State` in FPP becomes a qualified name such as `Switch::State` when translating to {cpp}. However, the F Prime XML format does not support the definition of constants and types as members of {cpp} components. -Therefore, when translating the previous example through XML to {cpp}, +Therefore, when translating the previous example to {cpp}, the following occurs: . The component `Switch` becomes an auto-generated {cpp} class diff --git a/docs/users-guide/Defining-Enums.adoc b/docs/users-guide/Defining-Enums.adoc index be3cc7062..6ade87aa9 100644 --- a/docs/users-guide/Defining-Enums.adoc +++ b/docs/users-guide/Defining-Enums.adoc @@ -168,14 +168,6 @@ This code defines an enum `Small` with three enumerated constants Each of the enumerated constants is represented as a `U8` value in {cpp}. -*GDS limitation:* -The F Prime GDS currently assumes that all enums use the default representation -size of `I32`. -Therefore, if you plan to use the F Prime GDS, then -you should not use any enum with a specified representation -type other than `I32` in the flight-ground interface (i.e., commands, events, telemetry, -and parameters). - === The Default Value Every type in FPP has an associated default value. diff --git a/docs/users-guide/Defining-Modules.adoc b/docs/users-guide/Defining-Modules.adoc index 124aa1ce1..0560b71ca 100644 --- a/docs/users-guide/Defining-Modules.adoc +++ b/docs/users-guide/Defining-Modules.adoc @@ -102,28 +102,3 @@ module M { constant a = 0 } ---- - -*XML limitation:* The F Prime XML format supports -only one level of {cpp} namespaces. -Therefore nested modules are not translated properly to {cpp}. -As a workaround, you can use an underscore prefix. -For example, instead of writing - -[source,fpp] ----- -module A { - module B { - - } -} ----- - -you can write - -[source,fpp] - ----- -module A_B { - -} ----- diff --git a/docs/users-guide/Defining-Topologies.adoc b/docs/users-guide/Defining-Topologies.adoc index b0ea38bad..2b5f3f7b5 100644 --- a/docs/users-guide/Defining-Topologies.adoc +++ b/docs/users-guide/Defining-Topologies.adoc @@ -76,7 +76,7 @@ named `C1` and `C2`. As shown, to write an instance specifier, you write the keyword `instance` and the name of a component instance definition. -In general the name may be a qualified name such as `A.B` +In general the name may be a qualified name such as `A.B`. if the instance is defined inside a <>; in this simple example it is not. diff --git a/docs/users-guide/Defining-Types.adoc b/docs/users-guide/Defining-Types.adoc index 43ddb9b7e..59fbb1ec4 100644 --- a/docs/users-guide/Defining-Types.adoc +++ b/docs/users-guide/Defining-Types.adoc @@ -477,12 +477,6 @@ struct S { The member `x` of the struct `S` gets three copies of the value 10 specified for `x` in the default value expression. -*GDS limitation:* The F Prime GDS does not properly handle -member arrays. -Therefore, if you plan to use the F Prime GDS, then you should avoid -using a struct type with a member array in the flight-ground interface (i.e., -commands, events, telemetry, and parameters). - ==== Member Format Strings For any struct member, you can include an optional format. diff --git a/docs/users-guide/Introduction.adoc b/docs/users-guide/Introduction.adoc index ce34282c8..e26224c63 100644 --- a/docs/users-guide/Introduction.adoc +++ b/docs/users-guide/Introduction.adoc @@ -17,7 +17,7 @@ well-tailored to its purpose. * To provide semantic checking and error reporting for F Prime models. * To generate code in the various languages that F Prime uses, e.g., -{cpp}, Python, XML. +{cpp}, JSON, and XML. In this document, we will call these languages the *target languages*. Developers may combine code generated from FPP with code written by hand to @@ -38,21 +38,6 @@ https://fprime-community.github.io/fpp/fpp-spec.html[_The FPP Language Specification_]. We recommend that you read this document before consulting that one. -*XML limitations:* -As of this writing, F Prime still uses an older XML format, e.g., -to support the Ground Data System (GDS). -Some features of FPP are not supported in the XML representation. -Where a feature is not supported in XML, we will call out this fact in a -note marked *XML limitation*. -As we phase out the XML code generation, we will phase in support -for all the features described here. - -*GDS limitations:* -It is currently possible to construct FPP models that are not -fully supported by the F Prime Ground Data System (GDS). -Where an FPP feature is not supported in the GDS, we will call out this -fact in a note marked *GDS limitation.* - *Overview:* The rest of this document proceeds as follows. Section 2 explains how to get up and running with FPP. Sections 3 through 11 describe the elements of an FPP From 04d92043c153b91e01cdbabedcbae36f90a752bb Mon Sep 17 00:00:00 2001 From: Rob Bocchino Date: Tue, 25 Jun 2024 13:03:27 -0700 Subject: [PATCH 3/7] Update version stamp to v2.1.0 --- docs/fpp-spec.html | 6 +++--- docs/fpp-users-guide.html | 6 +++--- version.sh | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index ed5e4aa3a..5e580983b 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -5,7 +5,7 @@ -The F Prime Prime (FPP) Language Specification, Unreleased, after v2.0.2 +The F Prime Prime (FPP) Language Specification, v2.1.0