Merge pull request nasa#1083 from skliper/fix793-reload_restart_doc

Fix nasa#793, Clarify restart/reload app behavior
jphickey · Feb 3, 2021 · 11201fa · 11201fa
2 parents eff9a87 + 3811351
commit 11201fa
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 19 deletions.
diff --git a/docs/src/cfe_es.dox b/docs/src/cfe_es.dox
@@ -366,9 +366,16 @@
 /**
   \page cfeesugapprestart Restarting an Application
 
-  The  #CFE_ES_RESTART_APP_CC command is used to restart an application. 
-  This command stops and restarts an application using the parameters 
-  defined when the application was originally started, either through 
+  The #CFE_ES_RESTART_APP_CC command is used to restart an application
+  using the same file name as the last start.
+
+  This command checks for file existence, the application is running,
+  and the application is not a core app.  If valid, the application restart
+  is requested.
+
+  When requested, ES stops the application, unloads the object file, loads the object file
+  using the previous file name, and restarts an application using the parameters
+  defined when the application was previously started, either through
   the startup script or by way of the #CFE_ES_START_APP_CC command. 
 
   Next: \ref cfeesugappreload <BR>
@@ -379,12 +386,11 @@
 /**
   \page cfeesugappreload Reloading an Application
 
-  The  #CFE_ES_RELOAD_APP_CC command is used to reload an application. 
-  This command stops the application, unloads the object file, loads 
-  the new object file specified in the command and starts the application 
-  again using the parameters defined when the application was originally 
-  started, either through the startup script or by way of the 
-  #CFE_ES_START_APP_CC command. 
+  The #CFE_ES_RELOAD_APP_CC command is used to reload an application
+  using a new file name.
+
+  This command performes
+  the same actions as #CFE_ES_RESTART_APP_CC only using the new file.
 
   Next: \ref cfeesugapplist <BR>
   Prev: \ref cfeesugapprestart <BR>

diff --git a/fsw/cfe-core/src/inc/cfe_es.h b/fsw/cfe-core/src/inc/cfe_es.h
@@ -359,10 +359,23 @@ CFE_Status_t  CFE_ES_ResetCFE(uint32 ResetType);
 ** \brief Restart a single cFE Application
 **
 ** \par Description
-**        This API causes a cFE Application to be stopped and restarted.
+**        This API causes a cFE Application to be unloaded and restarted
+**        from the same file name as the last start.
 **
 ** \par Assumptions, External Events, and Notes:
-**          None
+**        The filename is checked for existance prior to load.  A missing file
+**        will be reported and the reload operation will be aborted prior
+**        to unloading the app.
+**
+**        Goes through the standard CFE_ES_CleanUpApp which unloads,
+**        then attempts a load using the original file name.
+**
+**        In the event that an application cannot be reloaded due to a
+**        missing file or any other load issue, the application may no longer be
+**        restarted or reloaded when given a valid load file (the app has been
+**        deleted and no longer exists).  To recover, the application
+**        may be started by loading the application via the ES_STARTAPP
+**        command (#CFE_ES_START_APP_CC).
 **
 ** \param[in]  AppID       Identifies the application to be reset.
 **
@@ -382,11 +395,17 @@ CFE_Status_t CFE_ES_RestartApp(CFE_ES_ResourceID_t AppID);
 **        the specified file.
 **
 ** \par Assumptions, External Events, and Notes:
-**        The specified application will be deleted before it is reloaded from the
-**        specified file.  In the event that an application cannot be reloaded due to
+**        The filename is checked for existance prior to load.  A missing file
+**        will be reported and the reload operation will be aborted prior
+**        to unloading the app.
+**
+**        Goes through the standard CFE_ES_CleanUpApp which unloads,
+**        then attempts a load using the specified file name.
+**
+**        In the event that an application cannot be reloaded due to
 **        a corrupt file, the application may no longer be reloaded when given a valid
 **        load file (it has been deleted and no longer exists).  To recover, the
-**        application may be restarted by loading the application via the ES_STARTAPP
+**        application may be started by loading the application via the ES_STARTAPP
 **        command (#CFE_ES_START_APP_CC).
 **
 ** \param[in]  AppID       Identifies the application to be reset.

diff --git a/fsw/cfe-core/src/inc/cfe_es_msg.h b/fsw/cfe-core/src/inc/cfe_es_msg.h
@@ -267,12 +267,15 @@
 */
 #define CFE_ES_STOP_APP_CC             5
 
-/** \cfeescmd Stops and Restarts an Application
+/** \cfeescmd Stops, Unloads, Loads using the previous File name, and Restarts an Application
 **
 **  \par Description
-**       This command halts and restarts the specified Application.
-**       This command does \b NOT reload the application from the onboard
-**       filesystem.
+**       This command halts and removes the specified Application
+**       from the system.  Then it immediately loads the Application from
+**       the same filename last used to start.  This command is
+**       especially useful for restarting a Command Ingest Application
+**       since once it has been stopped, no further commands can come in
+**       to restart it.
 **
 **  \cfecmdmnemonic \ES_RESTARTAPP
 **
@@ -291,6 +294,7 @@
 **  \par Error Conditions
 **       This command may fail for the following reason(s):
 **       - The command packet length is incorrect
+**       - The original file is missing
 **       - The specified application name is not recognized as an active application
 **       - The specified application is one of the cFE's Core applications (ES, EVS, SB, TBL, TIME)
 **
@@ -310,7 +314,7 @@
 */
 #define CFE_ES_RESTART_APP_CC          6
 
-/** \cfeescmd Stops, Unloads, Loads from a File and Restarts an Application
+/** \cfeescmd Stops, Unloads, Loads from the command specfied File and Restarts an Application
 **
 **  \par Description
 **       This command halts and removes the specified Application
@@ -337,6 +341,7 @@
 **  \par Error Conditions
 **       This command may fail for the following reason(s):
 **       - The command packet length is incorrect
+**       - The reload file is missing
 **       - The specified application name is not recognized as an active application
 **       - The specified application is one of the cFE's Core applications (ES, EVS, SB, TBL, TIME)
 **