From 77cd2d1324c735238eff725166dded34ba5103ae Mon Sep 17 00:00:00 2001 From: watney Date: Thu, 25 Jul 2024 11:26:16 -0700 Subject: [PATCH 1/7] Update the state machine specification for do actions as lists --- docs/fpp-spec.html | 562 ++++++++++++------ docs/fpp-users-guide.html | 173 +++--- docs/index.html | 167 +++--- .../Do-Expressions.adoc | 45 ++ .../Enter-Expressions.adoc | 28 +- .../Initial-Transition-Specifiers.adoc | 9 +- .../Junction-Definitions.adoc | 5 +- .../State-Definitions.adoc | 40 +- .../State-Entry-Specifiers.adoc | 31 + .../State-Exit-Specifiers.adoc | 31 + .../State-Transition-Specifiers.adoc | 26 +- .../State-Machine-Behavior-Elements/defs.sh | 3 + 12 files changed, 747 insertions(+), 373 deletions(-) create mode 100644 docs/spec/State-Machine-Behavior-Elements/Do-Expressions.adoc create mode 100644 docs/spec/State-Machine-Behavior-Elements/State-Entry-Specifiers.adoc create mode 100644 docs/spec/State-Machine-Behavior-Elements/State-Exit-Specifiers.adoc diff --git a/docs/fpp-spec.html b/docs/fpp-spec.html index aa2dfab24..97f60cbb2 100644 --- a/docs/fpp-spec.html +++ b/docs/fpp-spec.html @@ -4,23 +4,25 @@ - + The F Prime Prime (FPP) Language Specification, State Machines -
-

6.2. Enter Expressions

+

6.2. Do Expressions

+
+

An do expression specifies a list of actions as part of an +initial transition, +a state transition, +a state entry, +a state exit, +or +a junction.

+
+
+

6.2.1. Syntax

+
+

do {action-sequence}

+
+
+

action-sequence is an +element sequence in +which each element is an identifier +and the terminating punctuation is a comma.

+
+
+
+

6.2.2. Semantics

+
+
    +
  1. +

    The action-sequence after the keyword do must +refer +to a list of +action definitions.

    +
    2. +
+
+
+
+

6.2.3. Examples

+
+
+
state machine Device {
+
+  action powerActuator
+  action powerGyro
+  action powerGimbal
+
+  state ON {
+    enter do {
+      powerActuator
+      powerGyro
+      powerGimbal
+    }
+  }
+
+}
+
+
+
+
+
+

6.3. Enter Expressions

An enter expression specifies a transition as part of an initial transition, @@ -3795,24 +3877,20 @@

6.2. Enter Expression some action.

-

6.2.1. Syntax

+

6.3.1. Syntax

[ -do identifier +do-expression ] enter qual-ident

-

6.2.2. Semantics

+

6.3.2. Semantics

  1. -

    If present, the optional identifier after the keyword do must -refer -to an -action definition. -It specifies an action to perform when making the transition.

    +

    If present, the do-expression specifies the list of actions to be performed

  2. The qualified identifier after the keyword enter must @@ -3827,32 +3905,30 @@

    6.2.2. Sema

-

6.2.3. Examples

+

6.3.3. Examples

state machine Device {
 
-  signal PowerOn
-
-  action getReady
+  action initDev1
+  action initDev2
 
-  guard initComplete
-
-  initial enter OFF
-
-  state OFF {
-    on PowerOn if initComplete do getReady enter ON
+  initial do {
+    initDev1
+    initDev2
   }
+  enter OFF
 
-  state ON
+  state OFF {
 
+  }
 }
-

6.3. Guard Definitions

+

6.4. Guard Definitions

A guard definition is part of a state machine definition. @@ -3865,7 +3941,7 @@

6.3. Guard Definition or the branch of the junction is taken.

-

6.3.1. Syntax

+

6.4.1. Syntax

guard identifier @@ -3876,7 +3952,7 @@

6.3.1. Syntax<

-

6.3.2. Semantics

+

6.4.2. Semantics

  1. @@ -3893,7 +3969,7 @@

    6.3.2. Sema

-

6.3.3. Examples

+

6.4.3. Examples

enum EnabledStatus { ENABLED, DISABLED }
@@ -3921,7 +3997,7 @@ 
6.3.3. Examp
-

6.4. Initial Transition Specifiers

+

6.5. Initial Transition Specifiers

An initial transition specifier is part of a state machine definition @@ -3932,14 +4008,14 @@

6.4. Init substates.

-

6.4.1. Syntax

+

6.5.1. Syntax

initial enter-expression

-

6.4.2. Semantics

+

6.5.2. Semantics

The state definition or junction definition referred to in the enter expression must be a member of the same @@ -3948,12 +4024,13 @@

-

6.4.3. Examples

+

6.5.3. Examples

state machine Device {
 
-  action initDevices
+  action initDev1
+  action initDev2
 
   # When the state machine starts up, enter the ON state
   initial enter ON
@@ -3961,7 +4038,11 @@ 

   state ON {
 
     # When entering the ON state, enter the POWERING_UP substate
-    initial do initDevices enter POWERING_UP
+    initial do {
+      initDev1
+      initDev2
+    }
+    enter POWERING_UP
 
     state POWERING_UP
 
@@ -3973,7 +4054,7 @@
-

6.5. Junction Definitions

+

6.6. Junction Definitions

A junction definition specifies a junction as part of a state machine definition @@ -3983,7 +4064,7 @@

6.5. Junction Defi guard.

-

6.5.1. Syntax

+

6.6.1. Syntax

junction identifier { @@ -3993,7 +4074,7 @@

6.5.1. Synt

-

6.5.2. Semantics

+

6.6.2. Semantics

  1. @@ -4015,7 +4096,7 @@

    6.5.2. S

-

6.5.3. Examples

+

6.6.3. Examples

state machine Device {
@@ -4027,7 +4108,10 @@ 
6.5.3. Ex
 
   junction J1 {
     if coldStart enter OFF \
-    else do initPower enter ON
+    else do {
+      initPower
+    }
+    enter ON
   }
 
   state OFF
@@ -4040,7 +4124,7 @@ 
6.5.3. Ex
-

6.6. Signal Definitions

+

6.7. Signal Definitions

A signal definition is part of a state machine definition. @@ -4063,7 +4147,7 @@

6.6. Signal Definiti for that state.

-

6.6.1. Syntax

+

6.7.1. Syntax

signal identifier @@ -4074,7 +4158,7 @@

6.6.1. Syntax

-

6.6.2. Semantics

+

6.7.2. Semantics

  1. @@ -4089,7 +4173,7 @@

    6.6.2. Sem

-

6.6.3. Examples

+

6.7.3. Examples

struct FaultData {
@@ -4114,7 +4198,7 @@ 
6.6.3. Exam
-

6.7. State Definitions

+

6.8. State Definitions

A state definition is part of a state machine definition @@ -4125,7 +4209,7 @@

6.7. State Definition of states: S' is a substate of S.

-

6.7.1. Syntax

+

6.8.1. Syntax

state identifier [ { state-definition-member-sequence } ]

@@ -4151,11 +4235,17 @@

6.7.1. Syntax<

  • A state transition specifier

    • +
  • +

    A state entry specifier

    +
    • +
  • +

    A state exit specifier

    +

    • -

    6.7.2. Semantics

    +

    6.8.2. Semantics

    1. @@ -4188,7 +4278,7 @@

      6.7.2. Sema

    -

    6.7.3. Examples

    +

    6.8.3. Examples

    state machine MonitorSm {
@@ -4200,10 +4290,16 @@ 
    6.7.3. Examp
   signal Stop
   signal Fault
 
+  action init1
   action init2
   action doCalibrate
   action motorControl
   action reportFault
+  action heaterOff
+  action monitorOff
+  action heaterOn
+  action monitorOn
+  action stopMotor
 
   guard calibrateReady
 
@@ -4211,26 +4307,48 @@ 
    6.7.3. Examp
 
   state DEVICE_ON {
 
-    initial do init2 enter INITIALIZING
+    initial do {
+      init1
+      init2
+     }
+     enter INITIALIZING
 
     state INITIALIZING {
       on Complete enter IDLE
     }
 
     state IDLE {
+      entry do {
+        heaterOff
+        monitorOff
+      }
+      exit do {
+        heaterOn
+        monitorOn
+      }
       on Drive enter DRIVING
       on Calibrate if calibrateReady enter CALIBRATING
     }
 
     state CALIBRATING {
-      on RTI do doCalibrate
-      on Fault do reportFault enter Idle
+      on RTI do {
+        doCalibrate
+      }
+      on Fault do {
+        reportFault
+       }
+      enter Idle
       on Complete enter IDLE
     }
 
     state DRIVING {
-      on RTI do motorControl
-      on Stop enter IDLE
+      on RTI do {
+        motorControl
+      }
+      on Stop do {
+        stopMotor
+      }
+      enter IDLE
     }
 
   }
@@ -4241,14 +4359,100 @@ 
    6.7.3. Examp
    -

    6.8. State Transition Specifiers

    +

    6.9. State Entry Specifiers

    +
    +

    A state entry specifier is part of a +state definition. +It specifies the state’s entry actions

    +
    +
    +

    6.9.1. Syntax

    +
    +

    entry do-expression

    +
    +
    +
    +

    6.9.2. Semantics

    +
    +
      +
    1. +

      The do-expression specifies a list of entry actions that get executed +when entering a state

      +
      2. +
    +
    +
    +
    +

    6.9.3. Examples

    +
    +
    +
    state machine Device {
+
+  action heaterOn
+  action monitorOn
+
+  state RUNNING {
+    entry do {
+      heaterOn
+      monitorOn
+    }
+}
    +
    +
    +
    +
    +
    +

    6.10. State Exit Specifiers

    +
    +

    A state exit specifier is part of a +state definition. +It specifies the state’s exit actions

    +
    +
    +

    6.10.1. Syntax

    +
    +

    exit do-expression

    +
    +
    +
    +

    6.10.2. Semantics

    +
    +
      +
    1. +

      The do-expression specifies a list of exit actions that get executed +when exiting a state

      +
      2. +
    +
    +
    +
    +

    6.10.3. Examples

    +
    +
    +
    state machine Device {
+
+  action heaterOff
+  action monitorOff
+
+  state RUNNING {
+    exit do {
+      heaterOff
+      monitorOff
+    }
+}
    +
    +
    +
    +
    +
    +

    6.11. State Transition Specifiers

    A state transition specifier is part of a state definition. It specifies a transition from the state in which it appears.

    -

    6.8.1. Syntax

    +

    6.11.1. Syntax

    on identifier [ @@ -4265,17 +4469,23 @@

    6.8.

    enter-expression

  • -

    do identifier

    +

    do-expression

    • +
    +

    action-sequence is an +element sequence in +which each element is an identifier +and the terminating punctuation is a comma.

    +
    -

    6.8.2. Semantics

    +

    6.11.2. Semantics

    1. -

      The identifier after the keyword on must +

      The identifier after the keyword on must refer to a signal definition. @@ -4298,19 +4508,19 @@

      6

    2. Second form of the syntax specifies an -internal transition, i.e., an action to take while remaining +internal transition, i.e., a list of actions to take while remaining in the same state. When making an internal transition, the exit and re-entry code is not run. -The identifier after the keyword do must +The list of actions specified in the _do-expression) must refer -to an -action definition.

      +to a list of +action definitions.

    -

    6.8.3. Examples

    +

    6.11.3. Examples

    state machine Device {
@@ -4319,14 +4529,19 @@ 
    6.
   signal PowerOn
 
   action performStuff
-  action getReady
+  action powerHeater
+  action powerSensor
 
   guard initComplete
 
   initial enter OFF
 
   state OFF {
-    on PowerOn if initComplete do getReady enter ON
+    on PowerOn if initComplete do {
+      powerHeater
+      powerSensor
+    }
+    enter ON
   }
 
   state ON {
@@ -9741,9 +9956,10 @@ 
    21.4. Translation Tools
    + - + \ No newline at end of file diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 03d9d3723..394fc31ec 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -4,23 +4,25 @@ - + The F Prime Prime (FPP) User’s Guide, State Machines - + - + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 07e30b8d1..15e3c5b8f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,23 +4,25 @@ - + F Prime Prime (FPP) + - - + \ No newline at end of file diff --git a/docs/fpp-users-guide.html b/docs/fpp-users-guide.html index 394fc31ec..96e37e4fc 100644 --- a/docs/fpp-users-guide.html +++ b/docs/fpp-users-guide.html @@ -4,25 +4,23 @@ - + The F Prime Prime (FPP) User’s Guide, State Machines + - - + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 15e3c5b8f..5d3dd6e90 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,25 +4,23 @@ - + F Prime Prime (FPP)