Skip to content

Commit

Permalink
Merge pull request #455 from jwest115/issue-402-user-guide
Browse files Browse the repository at this point in the history 
Updated XML and GDS limitations #402
  • Loading branch information
@bocchino
bocchino authored Jun 26, 2024
2 parents 41c344a + e765a4a commit 2083d3b
Show file tree
Hide file tree
Showing 12 changed files with 35 additions and 160 deletions.
6 changes: 3 additions & 3 deletions docs/fpp-spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.20">
<title>The F Prime Prime (FPP) Language Specification, Unreleased, after v2.0.2</title>
<title>The F Prime Prime (FPP) Language Specification, v2.1.0</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
Expand Down Expand Up @@ -436,7 +436,7 @@
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>The F Prime Prime (FPP) Language Specification, Unreleased, after v2.0.2</h1>
<h1>The F Prime Prime (FPP) Language Specification, v2.1.0</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
Expand Down Expand Up @@ -8551,7 +8551,7 @@ <h3 id="Analysis-and-Translation_Translation-Tools">20.4. Translation Tools</h3>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-06-20 11:07:32 -0700
Last updated 2024-06-25 13:02:44 -0700
</div>
</div>
<script src="code-prettify/run_prettify.js"></script>
Expand Down
96 changes: 15 additions & 81 deletions docs/fpp-users-guide.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.20">
<title>The F Prime Prime (FPP) User&#8217;s Guide, Unreleased, after v2.0.2</title>
<title>The F Prime Prime (FPP) User&#8217;s Guide, v2.1.0</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
Expand Down Expand Up @@ -436,7 +436,7 @@
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>The F Prime Prime (FPP) User&#8217;s Guide, Unreleased, after v2.0.2</h1>
<h1>The F Prime Prime (FPP) User&#8217;s Guide, v2.1.0</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
Expand Down Expand Up @@ -739,7 +739,7 @@ <h2 id="Introduction">1. Introduction</h2>
</li>
<li>
<p>To generate code in the various languages that F Prime uses, e.g.,
C&#43;&#43;, Python, XML.
C&#43;&#43;, JSON, and XML.
In this document, we will call these languages the <strong>target languages</strong>.</p>
</li>
</ul>
Expand All @@ -766,23 +766,6 @@ <h2 id="Introduction">1. Introduction</h2>
We recommend that you read this document before consulting that one.</p>
</div>
<div class="paragraph">
<p><strong>XML limitations:</strong>
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 <strong>XML limitation</strong>.
As we phase out the XML code generation, we will phase in support
for all the features described here.</p>
</div>
<div class="paragraph">
<p><strong>GDS limitations:</strong>
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 <strong>GDS limitation.</strong></p>
</div>
<div class="paragraph">
<p><strong>Overview:</strong> 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
Expand All @@ -793,7 +776,7 @@ <h2 id="Introduction">1. Introduction</h2>
of files: for example, it covers the management of dependencies
between files.
Section 13 explains how to analyze FPP models and how
to translate FPP models to XML, to C&#43;&#43;, and from XML.
to translate FPP models to and from XML, to C&#43;&#43;, and to JSON.
Section 14 explains how to write a C&#43;&#43; implementation
against the code generated from an FPP model.</p>
</div>
Expand Down Expand Up @@ -1942,32 +1925,6 @@ <h2 id="Defining-Modules">5. Defining Modules</h2>
<pre class="prettyprint highlight"><code data-lang="fpp">@ This is module M
module M {
constant a = 0
}</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>XML limitation:</strong> The F Prime XML format supports
only one level of C&#43;&#43; namespaces.
Therefore nested modules are not translated properly to C&#43;&#43;.
As a workaround, you can use an underscore prefix.
For example, instead of writing</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">module A {
module B {

}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>you can write</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code data-lang="fpp">module A_B {

}</code></pre>
</div>
</div>
Expand All @@ -1981,7 +1938,7 @@ <h2 id="Defining-Types">6. Defining Types</h2>
These definitions describe named types that may be used elsewhere in the
model and that may generate code in the target language.
For example,
an FPP type definition may become a class definition in C&#43;&#43; or Python.</p>
an FPP type definition may become a class definition in C&#43;&#43;.</p>
</div>
<div class="paragraph">
<p>There are three kinds of type definitions:</p>
Expand Down Expand Up @@ -2576,13 +2533,6 @@ <h4 id="Defining-Types_Struct-Type-Definitions_Member-Arrays">6.2.4. Member Arra
<p>The member <code>x</code> of the struct <code>S</code> gets three copies of the value
10 specified for <code>x</code> in the default value expression.</p>
</div>
<div class="paragraph">
<p><strong>GDS limitation:</strong> 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).</p>
</div>
</div>
<div class="sect3">
<h4 id="Defining-Types_Struct-Type-Definitions_Member-Format-Strings">6.2.5. Member Format Strings</h4>
Expand Down Expand Up @@ -2997,15 +2947,6 @@ <h3 id="Defining-Enums_The-Representation-Type">7.4. The Representation Type</h3
Each of the enumerated constants is represented as a <code>U8</code> value
in C&#43;&#43;.</p>
</div>
<div class="paragraph">
<p><strong>GDS limitation:</strong>
The F Prime GDS currently assumes that all enums use the default representation
size of <code>I32</code>.
Therefore, if you plan to use the F Prime GDS, then
you should not use any enum with a specified representation
type other than <code>I32</code> in the flight-ground interface (i.e., commands, events, telemetry,
and parameters).</p>
</div>
</div>
<div class="sect2">
<h3 id="Defining-Enums_The-Default-Value">7.5. The Default Value</h3>
Expand Down Expand Up @@ -5685,11 +5626,6 @@ <h4 id="Defining-Components_Telemetry_Limits">9.7.5. Limits</h4>
each of whose members satisfies condition (1) or
condition (2).</p>
</div>
<div class="paragraph">
<p><strong>XML limitation:</strong> The F Prime XML representation does
not allow limits for telemetry channels
of array or struct type.</p>
</div>
</div>
</div>
<div class="sect2">
Expand Down Expand Up @@ -6399,12 +6335,12 @@ <h3 id="Defining-Components_Constants-and-Types">9.10. Constants and Types</h3>
and prevents name clashes.</p>
</div>
<div class="paragraph">
<p><strong>XML limitation:</strong> In most cases, a qualified name such as <code>Switch.State</code>
<p>In most cases, a qualified name such as <code>Switch.State</code>
in FPP becomes a qualified name such as <code>Switch::State</code> when translating
to C&#43;&#43;.
However, the F Prime XML format does not support the definition
of constants and types as members of C&#43;&#43; components.
Therefore, when translating the previous example through XML to C&#43;&#43;,
Therefore, when translating the previous example to C&#43;&#43;,
the following occurs:</p>
</div>
<div class="olist arabic">
Expand Down Expand Up @@ -7533,7 +7469,7 @@ <h3 id="Defining-Topologies_A-Simple-Example">11.1. A Simple Example</h3>
<p>As shown, to write an instance specifier, you write the
keyword <code>instance</code> and the name of a component instance
definition.
In general the name may be a qualified name such as <code>A.B</code>
In general the name may be a qualified name such as <code>A.B</code>.
if the instance is defined inside a
<a href="#Defining-Modules">module</a>; in this simple
example it is not.
Expand Down Expand Up @@ -10022,7 +9958,11 @@ <h3 id="Analyzing-and-Translating-Models_Checking-Models">13.1. Checking Models<
<div class="sect2">
<h3 id="Analyzing-and-Translating-Models_Generating-XML">13.2. Generating XML</h3>
<div class="paragraph">
<p>This section describes how to generate XML from FPP.</p>
<p>We are phasing out the use of XML in favor of generating
JSON and directly generating C&#43;&#43;.
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.</p>
</div>
<div class="paragraph">
<p><strong>XML file names:</strong> The table <a href="#xml-file-names">XML File Names</a> shows how FPP definitions are
Expand Down Expand Up @@ -10329,12 +10269,6 @@ <h3 id="Analyzing-and-Translating-Models_Generating-XML">13.2. Generating XML</h
you can provide FPP source on standard input, as described
for <a href="#Analyzing-and-Translating-Models_Checking-Models"><code>fpp-check</code></a>.</p>
</div>
<div class="paragraph">
<p><strong>XML limitations:</strong> The XML translation has several
limitations.
For more information, see the text marked <strong>XML limitations</strong> elsewhere
in this manual.</p>
</div>
</div>
<div class="sect2">
<h3 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus">13.3. Generating C Plus Plus</h3>
Expand Down Expand Up @@ -10611,7 +10545,7 @@ <h4 id="Analyzing-and-Translating-Models_Generating-C-Plus-Plus_Constant-Definit
<a href="#Analyzing-and-Translating-Models_Generating-XML"><code>fpp-to-xml</code></a>.</p>
</li>
<li>
<p><code>-n</code> <em>file</em> : Write the names of the generated XML files
<p><code>-n</code> <em>file</em> : Write the names of the generated C&#43;&#43; files
to <em>file</em>.
This is similar to the <code>-n</code> option for
<a href="#Analyzing-and-Translating-Models_Generating-XML"><code>fpp-to-xml</code></a>.</p>
Expand Down Expand Up @@ -12360,7 +12294,7 @@ <h4 id="Writing-C-Plus-Plus-Implementations_Implementing-Deployments_Public-Symb
</div>
<div id="footer">
<div id="footer-text">
Last updated 2024-06-20 11:08:28 -0700
Last updated 2024-06-26 08:38:10 -0700
</div>
</div>
<script src="code-prettify/run_prettify.js"></script>
Expand Down
6 changes: 3 additions & 3 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -453,17 +453,17 @@ <h1>F Prime Prime (FPP)</h1>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/fprime-community/fpp">The FPP repository on GitHub</a>.</p>
<p><a href="https://github.com/nasa/fpp">The FPP repository on GitHub</a>.</p>
</li>
<li>
<p><a href="https://github.com/fprime-community/fpp/wiki">The FPP wiki</a>.</p>
<p><a href="https://github.com/nasa/fpp/wiki">The FPP wiki</a>.</p>
</li>
</ul>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2021-10-04 10:03:10 -0700
Last updated 2024-06-25 13:07:03 -0700
</div>
</div>
</body>
Expand Down
4 changes: 2 additions & 2 deletions docs/index/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,6 @@ generated code.

For more information on FPP, see the following resources:

* https://github.com/fprime-community/fpp[The FPP repository on GitHub].
* https://github.com/nasa/fpp[The FPP repository on GitHub].
* https://github.com/fprime-community/fpp/wiki[The FPP wiki].
* https://github.com/nasa/fpp/wiki[The FPP wiki].
11 changes: 5 additions & 6 deletions docs/users-guide/Analyzing-and-Translating-Models.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,10 @@ even though `c.Out` has two ports and only one of them is connected.

=== Generating XML

We are phasing out the use of XML 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 <<xml-file-names>> shows how FPP definitions are
Expand Down Expand Up @@ -348,11 +352,6 @@ an automatic default of 80.
you can provide FPP source on standard input, as described
for <<Analyzing-and-Translating-Models_Checking-Models,`fpp-check`>>.

*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.
Expand Down Expand Up @@ -542,7 +541,7 @@ the output directory for writing files.
This is similar to the `-d` option for
<<Analyzing-and-Translating-Models_Generating-XML, `fpp-to-xml`>>.

* `-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
<<Analyzing-and-Translating-Models_Generating-XML, `fpp-to-xml`>>.
Expand Down
8 changes: 2 additions & 6 deletions docs/users-guide/Defining-Components.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
8 changes: 0 additions & 8 deletions docs/users-guide/Defining-Enums.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 0 additions & 25 deletions docs/users-guide/Defining-Modules.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
}
----
2 changes: 1 addition & 1 deletion docs/users-guide/Defining-Topologies.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<<Defining-Modules,module>>; in this simple
example it is not.
Expand Down
Loading

0 comments on commit 2083d3b

Please sign in to comment.