From 542e451862d8ada18a6a5581ee0db3bfd45d0046 Mon Sep 17 00:00:00 2001 From: Jacob Hageman Date: Mon, 7 Jun 2021 20:04:36 +0000 Subject: [PATCH] Fix #1306, ES/ResourceID documentation cleanup --- cmake/global_functions.cmake | 25 ++++++++++++++++--------- cmake/sample_defs/targets.cmake | 1 + cmake/target/src/target_config.c | 17 ++++++++++------- modules/core_api/fsw/inc/cfe_es.h | 9 ++++----- modules/es/fsw/src/cfe_es_api.c | 7 ++++--- modules/es/fsw/src/cfe_es_erlog.c | 8 +------- modules/es/fsw/src/cfe_es_objtab.c | 2 +- modules/es/fsw/src/cfe_es_start.c | 2 +- 8 files changed, 38 insertions(+), 33 deletions(-) diff --git a/cmake/global_functions.cmake b/cmake/global_functions.cmake index 8289363cc..38477192c 100644 --- a/cmake/global_functions.cmake +++ b/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 variables are defined, they are translated to name +# based list of MISSION_CPUNAMES (from TGT_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_: set for each entry of TGTSYS_LIST, and indicates the -# toolchain specified in the target file for that CPU arch. -# TGTSYS_: set to a list of CPU numbers that utilize the same arch -# TGTSYS__APPS: set for each entry of TGTSYS_LIST, and indicates the -# full set of applications that need to built for that target architecture -# TGTSYS__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_: list of CPU names that utilize the same architecture +# TGTSYS__APPS: list of apps for the architecture +# TGTSYS__STATICAPPS: list of static apps for the architecture +# TGTSYS__PSPMODULES: list of psp modules for the architecture # function(read_targetconfig) diff --git a/cmake/sample_defs/targets.cmake b/cmake/sample_defs/targets.cmake index d2ea58a7b..6301a0984 100644 --- a/cmake/sample_defs/targets.cmake +++ b/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. +# _PROCESSORID : numerical identifier for the processor # _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 diff --git a/cmake/target/src/target_config.c b/cmake/target/src/target_config.c index 2995bd73c..99697fd5d 100644 --- a/cmake/target/src/target_config.c +++ b/cmake/target/src/target_config.c @@ -71,7 +71,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 @@ -84,7 +85,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 @@ -93,8 +95,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. */ @@ -103,8 +105,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. * @@ -122,7 +124,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. diff --git a/modules/core_api/fsw/inc/cfe_es.h b/modules/core_api/fsw/inc/cfe_es.h index 957838aff..8385c7274 100644 --- a/modules/core_api/fsw/inc/cfe_es.h +++ b/modules/core_api/fsw/inc/cfe_es.h @@ -387,14 +387,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 @@ -794,8 +793,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. ** @@ -1491,7 +1489,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. diff --git a/modules/es/fsw/src/cfe_es_api.c b/modules/es/fsw/src/cfe_es_api.c index e58327320..c3459dda9 100644 --- a/modules/es/fsw/src/cfe_es_api.c +++ b/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; diff --git a/modules/es/fsw/src/cfe_es_erlog.c b/modules/es/fsw/src/cfe_es_erlog.c index 736fecae7..ae92b4841 100644 --- a/modules/es/fsw/src/cfe_es_erlog.c +++ b/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: diff --git a/modules/es/fsw/src/cfe_es_objtab.c b/modules/es/fsw/src/cfe_es_objtab.c index 2d8782e75..6bf370f3b 100644 --- a/modules/es/fsw/src/cfe_es_objtab.c +++ b/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 diff --git a/modules/es/fsw/src/cfe_es_start.c b/modules/es/fsw/src/cfe_es_start.c index ec550bfa1..25d02cdad 100644 --- a/modules/es/fsw/src/cfe_es_start.c +++ b/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);