Add Phase 1 state machines to User's Guide

docs/fpp-spec.html

@@ -9740,7 +9740,7 @@ <h3 id="Analysis-and-Translation_Translation-Tools">21.4. Translation Tools</h3>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-08-05 09:51:25 -0600
+Last updated 2024-08-05 22:39:03 -0600
 </div>
 </div>
 <script src="code-prettify/run_prettify.js"></script>

docs/index.html

@@ -463,7 +463,7 @@ <h1>F Prime Prime (FPP)</h1>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2024-07-16 14:57:58 -0700
+Last updated 2024-07-20 12:45:03 -0700
 </div>
 </div>
 </body>

docs/users-guide/Analyzing-and-Translating-Models.adoc

@@ -490,7 +490,8 @@ Notice how the FPP annotations are translated to comments.
 
 *Constants defined inside components:*
 As noted in the section on
-<<Defining-Components_Constants-and-Types,defining components>>,
+<<Defining-Components_Constants-Types-Enums-and-State-Machines,
+defining components>>,
 when you define a constant `c` inside a component `C`,
 the name of the corresponding constant in the generated {cpp}
 code is `C_c`.

docs/users-guide/Defining-Components.adoc

@@ -189,8 +189,11 @@ 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 (described below);
-or it must have at least one async command (also described below).
+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.
@@ -2295,7 +2298,7 @@ Here is an example:
 @ A struct type defining some data
 struct Data { a: U32, b: F32 }
 
-@ A component for illustrating data product 
+@ A component for illustrating data product identifiers
 passive component DataProductIdentifiers {
 
   # ----------------------------------------------------------------------
@@ -2404,10 +2407,70 @@ 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.
 
-=== Constants and Types
+=== State Machine Instances
 
-You can write a <<Defining-Constants,constant definition>>
-or <<Defining-Types,type definition>>
+A *state machine instance* is a component member that instantiates
+an FPP <<Defining-State-Machines,state machine>>.
+The state machine instance becomes part of the component implementation.
+
+For example, here is a simple async component that has
+one state machine instance and one async input port
+for driving the state machine:
+
+[source,fpp]
+----
+@ An external state machine
+state machine M
+
+@ A component with a state machine
+active component StateMachine {
+
+  @ A port for driving the state machine
+  async input port schedIn: Svc.Sched
+
+  @ An instance of state machine M
+  state machine instance m: M
+
+}
+----
+
+When a state machine instance _m_ is part of a component _C_,
+each instance _c_ of _C_ sends _m_ *signals* to process as it runs.
+Signals occur in response to commands or port
+invocations received by _c_, and they tell _m_ when to change state.
+_c_ puts the signals on its queue, and _m_ dispatches them.
+Therefore, if a component _C_ has a state machine instance member _m_,
+then its instances _c_ must have queues, i.e., _C_ must be active or queued.
+
+As with <<Defining-Components_Internal-Ports,internal ports>>,
+you may specify priority and queue full behavior associated
+with the signals dispatched by a state machine instance.
+For example, we can revise the example above as follows:
+
+[source,fpp]
+----
+@ An external state machine
+state machine M
+
+@ A component with a state machine
+active component StateMachine {
+
+  @ A port for driving the state machine
+  async input port schedIn: Svc.Sched
+
+  @ An instance of state machine M
+  state machine instance m: M priority 10 drop
+
+}
+----
+
+=== Constants, Types, Enums, and State Machines
+
+You can write a <<Defining-Constants,constant definition>>,
+<<Defining-Types,type definition>>, 
+<<Defining-Enums,enum definition>>, 
+or
+<<Defining-State-Machines,state machine definition>>
 as a component member.
 When you do this, the component qualifies
 the name of the constant or type, similarly to the way that a

docs/users-guide/Defining-State-Machines.adoc

@@ -0,0 +1,70 @@
+== Defining State Machines
+
+A *hierarchical state machine* (state machine for short)
+specifies the following:
+
+* A set of *states* that a system can be in.
+The states can be arranged in a hierarchy (i.e.,
+states may have substates).
+
+* A set of *transitions* from one state to another that
+occur under specified conditions.
+
+State machines are important in embedded programming.
+For example, F Prime components often have a concept of state
+that changes as the system runs, and it is useful to model
+these state changes as a state machine.
+
+In FPP there are two ways to define a state machine:
+
+. An *external* state machine definition is similar to
+an <<Defining-Types_Abstract-Type-Definitions,abstract type definition>>:
+it tells the analyzer that a state machine exists with a specified
+name, but it says nothing about the state machine behavior.
+An external tool must provide the state machine implementation.
+
+. An *internal* state machine definition is similar to an
+<<Defining-Types_Array-Type-Definitions,array type definition>>
+or
+<<Defining-Types_Struct-Type-Definitions,struct type definition>>:
+it provides a complete specification in FPP of the state machine behavior.
+The FPP back end uses this specification to generate code;
+no external tool is required.
+
+As of the current version of FPP, only external state machines
+are implemented.
+Support for internal state machines is in development.
+
+State machine definitions may appear at the top level or inside a
+<<Defining-Modules,module definition>>.
+A state machine definition is an
+<<Writing-Comments-and-Annotations_Annotations,annotatable element>>.
+
+=== External State Machines
+
+To define an external state machine, you write the keywords
+`state` `machine` followed by an identifier, which is the
+name of the state machine:
+
+[source,fpp]
+----
+state machine M
+----
+
+This code defines an external state machine with name `M`.
+You can then
+<<Defining-Components_State-Machine-Instances,instantiate>>
+the state machine `M` in a component definition.
+
+When you define an external state machine `M`, you must provide
+an implementation for `M`, as discussed in the section
+on <<Writing-C-Plus-Plus-Implementations_Implementing-External-State-Machines,
+implementing external state machines>>.
+The external implementation must have a header file `M.hpp`
+located in the same directory as the FPP file where
+the state machine `M` is defined.
+
+=== Internal State Machines
+
+Support for internal state machines is in development.
+It will be available in a future release of FPP.

docs/users-guide/Defining-Types.adoc

@@ -642,7 +642,7 @@ In particular, when the target language is {cpp}, the default
 value is the zero-argument constructor `T()`.
 
 *Built-in types:*
-When translating to XML, there are a few special types that are abstract
+When translating FPP to {cpp}, there are a few special types that are abstract
 in the model, but that are known to the translator.
 You don't have to define {cpp} classes for these types.
 We will discuss these types further in the section on

docs/users-guide/Writing-C-Plus-Plus-Implementations.adoc

@@ -174,6 +174,22 @@ in the FPP model; for a typical F Prime project, these
 definitions are located at `config/FpConfig.fpp`.
 You don't have to define header files for these types.
 
+=== Implementing External State Machines
+
+An <<Defining-State-Machines_External-State-Machines,
+external state machine>> refers to a state machine implementation
+supplied outside the FPP model.
+To implement an external state machine, you can use 
+the https://github.com/JPLOpenSource/STARS/tree/main[State Autocoding for 
+Real-Time Systems (STARS)]
+tool.
+STARS provides several ways to specify state machines, and it
+provides several {cpp} back ends.
+The F Prime back end is designed to work with FPP code generation.
+
+For an example of an external state machine implemented in STARS,
+see `FppTest/state_machine` in the F Prime repository.
+
 === Implementing Deployments
 
 At the highest level of an F Prime implementation, you write

docs/users-guide/defs.sh

@@ -18,6 +18,7 @@ Defining-Modules.adoc
 Defining-Types.adoc
 Defining-Enums.adoc
 Defining-Ports.adoc
+Defining-State-Machines.adoc
 Defining-Components.adoc
 Defining-Component-Instances.adoc
 Defining-Topologies.adoc