Merge pull request #1610 from skliper/fix1306-es_rid_comments

Fix #1306, ES/ResourceID documentation cleanup

Author: astrogeco

cmake/global_functions.cmake

@@ -65,6 +65,7 @@ endfunction(generate_c_headerfile)
 # source file for the wrapper.
 #
 # This function now accepts named parameters:
+#   OUTPUT_DIRECTORY - non-default directory to write the file to (optional)
 #   FILE_NAME - the name of the file to write
 #   FALLBACK_FILE - if no files are found in "defs" using the name match, this file will be used instead.
 #   MATCH_SUFFIX - the suffix to match in the "defs" directory (optional)
@@ -130,18 +131,24 @@ endfunction(generate_config_includefile)
 # FUNCTION: read_targetconfig
 #
 # Scan the list of targets and organize by target system type.
-# This function sets up the following variables in the global scope:
+#
+# If the historical TGT<x> variables are defined, they are translated to name
+# based list of MISSION_CPUNAMES (from TGT<x>_NAMEs).  The historical settings
+# are then translated to the new cpuname based settings as defined in the
+# sample_defs/targets.cmake and sets them as global scope.
+#
+# This function then sets up the following variables in the global scope:
 #   TGTSYS_LIST: list of CPU architectures used in the build.  Note this
 #       will always contain a "native" target (for tools at least) which 
 #       is forced to be last.
-#   MISSION_APPS: full list of applications specified in the whole mission
-#   SYSID_<arch>: set for each entry of TGTSYS_LIST, and indicates the
-#       toolchain specified in the target file for that CPU arch.
-#   TGTSYS_<arch>: set to a list of CPU numbers that utilize the same arch 
-#   TGTSYS_<arch>_APPS: set for each entry of TGTSYS_LIST, and indicates the
-#       full set of applications that need to built for that target architecture
-#   TGTSYS_<arch>_DRIVERS: set for each entry of TGTSYS_LIST, and indicates the
-#       full set of device drivers that need to built for that target architecture
+#   MISSION_APPS: list of all applications in this build
+#   MISSION_PSPMODULES: list of all psp modules in this build
+#
+# Additionally for each architechture in TGTSYS_LIST:
+#   TGTSYS_<arch>: list of CPU names that utilize the same architecture
+#   TGTSYS_<arch>_APPS: list of apps for the architecture
+#   TGTSYS_<arch>_STATICAPPS: list of static apps for the architecture
+#   TGTSYS_<arch>_PSPMODULES: list of psp modules for the architecture
 #
 function(read_targetconfig)
 

cmake/sample_defs/targets.cmake

@@ -10,6 +10,7 @@
 #
 #  MISSION_CPUNAMES : list of user-friendly cpu names.  Should be simple
 #       words with no punctuation.  This MUST be specified.
+#  <cpuname>_PROCESSORID : numerical identifier for the processor
 #  <cpuname>_APPLIST : list of applications to build and install on the CPU.
 #       These are built as dynamically-loaded applications and installed
 #       as files in the non-volatile storage of the target, and loaded

cmake/target/src/target_config.c

@@ -67,7 +67,8 @@ extern const char CFE_MISSION_NAME[];   /**< Name of CFE mission */
 extern const char CFE_MISSION_CONFIG[]; /**< Configuration name used for build */
 
 /**
- * A list of modules which are statically linked into CFE core.
+ * A NULL terminated list of modules which are statically linked into CFE core,
+ * generated by the build system from MISSION_CORE_MODULES.
  *
  * For module names which appear in this list, the code is directly
  * linked into the core executable binary file, and therefore means
@@ -80,7 +81,8 @@ extern const char CFE_MISSION_CONFIG[]; /**< Configuration name used for build *
 extern CFE_ConfigName_t CFE_CORE_MODULE_LIST[];
 
 /**
- * A list of CFS apps which are also statically linked with this binary.
+ * A NULL terminated list of CFS apps which are also statically linked with this binary,
+ * generated by the build system from the target STATIC_APPLIST.
  *
  * These apps can be started without dynamically loading any modules,
  * however the entry point must be separately provided in order to avoid
@@ -89,8 +91,8 @@ extern CFE_ConfigName_t CFE_CORE_MODULE_LIST[];
 extern CFE_ConfigName_t CFE_STATIC_APP_LIST[];
 
 /**
- * A key-value table containing certain environment information from the build system
- * at the time CFE core was built.
+ * A NULL terminated key-value table containing certain environment information
+ * from the build system at the time CFE core was built.
  *
  * This contains basic information such as the time of day, build host, and user.
  */
@@ -99,8 +101,8 @@ extern CFE_ConfigKeyValue_t CFE_BUILD_ENV_TABLE[];
 /**
  * Version control (source code) versions of all modules
  *
- * This list includes all modules known to the build system as determined by the
- * version control system in use (e.g. git).  It is generated by a post-build step
+ * This NULL terminated list includes all modules known to the build system as determined
+ * by the version control system in use (e.g. git).  It is generated by a post-build step
  * to query version control and should change automatically every time code is
  * checked in or out.
  *
@@ -118,7 +120,8 @@ extern CFE_ConfigKeyValue_t CFE_BUILD_ENV_TABLE[];
 extern CFE_ConfigKeyValue_t CFE_MODULE_VERSION_TABLE[];
 
 /**
- * A list of PSP modules included in this build of CFE core.
+ * A NULL terminated list of PSP modules included in this build of CFE core,
+ * generated by the build system from the target PSPMODULES.
  *
  * These are always statically linked, and this table contains a pointer
  * to its API structure, which in turn contains its entry point.

modules/core_api/fsw/inc/cfe_es.h

@@ -389,14 +389,13 @@ bool CFE_ES_RunLoop(uint32 *RunStatus);
 **        to satisfy the global system state it is waiting for, and the apps own
 **        state will be updated accordingly.
 **
+** \param[in]  MinSystemState        Determine the state of the App
 ** \param[in]  TimeOutMilliseconds   The timeout value in Milliseconds.
 **                                   This parameter must be at least 1000. Lower values
 **                                   will be rounded up. There is not an option to
 **                                   wait indefinitely to avoid hanging a critical
 **                                   application because a non-critical app did not start.
 **
-** \param[in]  MinSystemState        Determine the state of the App
-**
 ** \return Execution status, see \ref CFEReturnCodes
 ** \retval #CFE_SUCCESS                State successfully achieved
 ** \retval #CFE_ES_OPERATION_TIMED_OUT Timeout was reached
@@ -796,8 +795,7 @@ int32 CFE_ES_GetModuleInfo(CFE_ES_AppInfo_t *ModuleInfo, CFE_ResourceId_t Resour
 ** \param[in]   StackSize     The number of bytes to allocate for the new task's stack.
 **
 ** \param[in]   Priority      The priority for the new task.  Lower numbers are higher priority, with 0 being
-**                            the highest priority.  Applications cannot create tasks with a higher priority
-**                            (lower number) than their own priority.
+**                            the highest priority.
 **
 ** \param[in]   Flags         Reserved for future expansion.
 **
@@ -1493,7 +1491,8 @@ void CFE_ES_PerfLogAdd(uint32 Marker, uint32 EntryExit);
 ** \brief Register a generic counter
 **
 ** \par Description
-**        This routine registers a generic counter.
+**        This routine registers a generic thread-safe counter which
+**        can be used for inter-task management.
 **
 ** \par Assumptions, External Events, and Notes:
 **        None.

modules/es/fsw/src/cfe_es_api.c

@@ -702,7 +702,7 @@ CFE_Status_t CFE_ES_GetAppIDByName(CFE_ES_AppId_t *AppIdPtr, const char *AppName
     {
         /*
          * ensure the output value is set to a safe value,
-         * in case the does not check the return code.
+         * in case the caller does not check the return code.
          */
         Result    = CFE_ES_ERR_NAME_NOT_FOUND;
         *AppIdPtr = CFE_ES_APPID_UNDEFINED;
@@ -743,7 +743,7 @@ CFE_Status_t CFE_ES_GetLibIDByName(CFE_ES_LibId_t *LibIdPtr, const char *LibName
     {
         /*
          * ensure the output value is set to a safe value,
-         * in case the does not check the return code.
+         * in case the caller does not check the return code.
          */
         Result    = CFE_ES_ERR_NAME_NOT_FOUND;
         *LibIdPtr = CFE_ES_LIBID_UNDEFINED;
@@ -1168,6 +1168,7 @@ int32 CFE_ES_GetModuleInfo(CFE_ES_AppInfo_t *ModuleInfo, CFE_ResourceId_t Resour
 {
     int32 Status;
 
+    /* Note - ModuleInfo NULL pointer check is perfromed by CFE_ES_GetAppInfo or CFE_ES_GetLibInfo */
     switch (CFE_ResourceId_GetBase(ResourceId))
     {
         case CFE_ES_APPID_BASE:
@@ -2078,7 +2079,7 @@ CFE_Status_t CFE_ES_GetGenCounterIDByName(CFE_ES_CounterId_t *CounterIdPtr, cons
     {
         /*
          * ensure the output value is set to a safe value,
-         * in case the does not check the return code.
+         * in case the caller does not check the return code.
          */
         Result        = CFE_ES_ERR_NAME_NOT_FOUND;
         *CounterIdPtr = CFE_ES_COUNTERID_UNDEFINED;

modules/es/fsw/src/cfe_es_erlog.c

@@ -245,13 +245,7 @@ void CFE_ES_BackgroundERLogFileEventHandler(void *Meta, CFE_FS_FileWriteEvent_t
 
     BgFilePtr = (CFE_ES_BackgroundLogDumpGlobal_t *)Meta;
 
-    /*
-     * Note that this runs in the context of ES background task (file writer background job)
-     * It does NOT run in the context of the CFE_TBL app task.
-     *
-     * Events should use CFE_EVS_SendEventWithAppID() rather than CFE_EVS_SendEvent()
-     * to get proper association with TBL task.
-     */
+    /* Note that this runs in the context of ES background task (file writer background job) */
     switch (Event)
     {
         case CFE_FS_FileWriteEvent_COMPLETE:

modules/es/fsw/src/cfe_es_objtab.c

@@ -23,7 +23,7 @@
 **    cfe_es_objtab.c
 **
 **   Purpose:
-**     This file contains the OS_object_table for MAP Build1.
+**     This file contains the OS_object_table for system initialization/startup.
 **
 **  References:
 **     Flight Software Branch C Coding Standard Version 1.0a

modules/es/fsw/src/cfe_es_start.c

@@ -101,7 +101,7 @@ void CFE_ES_Main(uint32 StartType, uint32 StartSubtype, uint32 ModeId, const cha
                   (unsigned int)ReturnCode);
 
         /*
-        ** Delay to allow the message to be read
+        ** Delay to allow the message to be printed
         */
         OS_TaskDelay(CFE_ES_PANIC_DELAY);