diff --git a/README.md b/README.md index c12459d88..c7d955648 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ This repository contains NASA's Core Flight Executive (cFE), which is a framewor This is a collection of services and associated framework to be located in the `cfe` subdirectory of a cFS Mission Tree. The Core Flight System is bundled at https://github.com/nasa/cFS, which includes build and execution instructions. ## Version Notes + +- 6.7.11: DEVELOPMENT + - Improve documentation + - Update makefile to report branch coverage + - Minor other updates (see https://github.com/nasa/cFE/pull/566) - 6.7.10: DEVELOPMENT - Fix potential unit test problems with name collisions - Improve documentation diff --git a/cmake/Makefile.sample b/cmake/Makefile.sample index 5c2c5e4cf..bea332e6f 100644 --- a/cmake/Makefile.sample +++ b/cmake/Makefile.sample @@ -16,33 +16,33 @@ # repository which is why it cannot be delivered directly in place. # To use it, simply copy it to the top directory. As this just contains # wrappers for the CMake targets, it is unlikely to change. Projects -# are also free to customize this file and add their own targets after +# are also free to customize this file and add their own targets after # copying it to the top of the source tree. # -# For _ALL_ targets defined in this file the build tree location may -# be specified via the "O" variable (i.e. make O= all). -# If not specified then the "build" subdirectory will be assumed. +# For _ALL_ targets defined in this file the build tree location may +# be specified via the "O" variable (i.e. make O= all). +# If not specified then the "build" subdirectory will be assumed. # # This wrapper defines the following major targets: # prep -- Runs CMake to create a new or re-configure an existing build tree # Note that multiple build trees can exist from a single source -# Other control options (such as "SIMULATION") may be passed to CMake via +# Other control options (such as "SIMULATION") may be passed to CMake via # make variables depending on the mission build scripts. These will be -# cached in the build tree so they do not need to be set again thereafter. +# cached in the build tree so they do not need to be set again thereafter. # # all -- Build all targets in the CMake build tree -# +# # install -- Copy all files to the installation tree and run packaging scripts -# The "DESTDIR" environment variable controls where the files are copied +# The "DESTDIR" environment variable controls where the files are copied # # clean -- Clean all targets in the CMake build tree, but not the build tree itself. # -# distclean -- Entirely remove the build directory specified by "O" +# distclean -- Entirely remove the build directory specified by "O" # Note that after this the "prep" step must be run again in order to build. # Use caution with this as it does an rm -rf - don't set O to your home dir! # # doc -- Build all doxygen source documentation. The HTML documentation will be -# generated under the build tree specified by "O". +# generated under the build tree specified by "O". # # usersguide -- Build all API/Cmd/Tlm doxygen documentation. The HTML documentation # will be generated under the build tree specified by "O". @@ -53,7 +53,7 @@ # test -- Run all unit tests defined in the build. Unit tests will typically only # be executable when building with the "SIMULATION=native" option. Otherwise # it is up to the user to copy the executables to the target and run them. -# +# # lcov -- Runs the "lcov" tool on the build tree to collect all code coverage # analysis data and build the reports. Code coverage data may be output by # the "make test" target above. @@ -91,7 +91,7 @@ $(DIRTGTS): endif # For any other goal that is not one of the known local targets, pass it to the arch build -# as there might be a target by that name. For example, this is useful for rebuilding +# as there might be a target by that name. For example, this is useful for rebuilding # single unit test executable files while debugging from the IDE FILETGTS := $(filter-out $(DIRTGTS),$(OTHERTGTS)) ifneq ($(FILETGTS),) @@ -103,7 +103,7 @@ endif # Certain special ones should be passed via cache (-D) options to CMake. # These are only needed for the "prep" target but they are computed globally anyway. PREP_OPTS := - + ifneq ($(INSTALLPREFIX),) PREP_OPTS += -DCMAKE_INSTALL_PREFIX=$(INSTALLPREFIX) endif @@ -125,7 +125,7 @@ install: prep $(O)/.prep: mkdir -p "$(O)" (cd "$(O)/$(BUILDDIR)" && cmake $(PREP_OPTS) "$(CURDIR)/cfe") - echo "$(PREP_OPTS)" > "$(O)/.prep" + echo "$(PREP_OPTS)" > "$(O)/.prep" clean: $(MAKE) --no-print-directory -C "$(O)" mission-clean @@ -139,10 +139,9 @@ test: (cd $(O)/$(ARCH) && ctest -O ctest.log) lcov: - lcov --capture --directory $(O)/$(ARCH) --output-file $(O)/$(ARCH)/coverage_test.info - lcov --add-tracefile $(O)/$(ARCH)/coverage_base.info --add-tracefile $(O)/$(ARCH)/coverage_test.info --output-file $(O)/$(ARCH)/coverage_total.info - lcov --remove $(O)/$(ARCH)/coverage_total.info 'unit-test/*' --output-file $(O)/$(ARCH)/coverage_filtered.info - genhtml $(O)/$(ARCH)/coverage_filtered.info --output-directory $(O)/$(ARCH)/lcov + lcov --capture --rc lcov_branch_coverage=1 --directory $(O)/$(ARCH) --output-file $(O)/$(ARCH)/coverage_test.info + lcov --rc lcov_branch_coverage=1 --add-tracefile $(O)/$(ARCH)/coverage_base.info --add-tracefile $(O)/$(ARCH)/coverage_test.info --output-file $(O)/$(ARCH)/coverage_total.info + genhtml $(O)/$(ARCH)/coverage_total.info --output-directory $(O)/$(ARCH)/lcov @/bin/echo -e "\n\nCoverage Report Link: file:$(CURDIR)/$(O)/$(ARCH)/lcov/index.html\n" doc: @@ -155,11 +154,10 @@ usersguide: osalguide: $(MAKE) --no-print-directory -C "$(O)" osalguide - @/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osal_guide/html/index.html\n" + @/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osalguide/html/index.html\n" # Make all the commands that use the build tree depend on a flag file # that is used to indicate the prep step has been done. This way # the prep step does not need to be done explicitly by the user # as long as the default options are sufficient. -$(filter-out prep distclean,$(LOCALTGTS)): $(O)/.prep - +$(filter-out prep distclean,$(LOCALTGTS)): $(O)/.prep diff --git a/cmake/cfe-common.doxyfile.in b/cmake/cfe-common.doxyfile.in index 3343853bd..5fb9965a1 100644 --- a/cmake/cfe-common.doxyfile.in +++ b/cmake/cfe-common.doxyfile.in @@ -7,7 +7,7 @@ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English OUTPUT_DIRECTORY = . BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = NO +REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class " \ "The $name widget " \ "The $name file " \ @@ -30,13 +30,6 @@ INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 8 ALIASES += "event=\xrefitem cfeevents \"Event Message\" \"cFE Event Message Cross Reference\" " \ - "retdesc= " \ - "retcode= " \ - endcode= \ - "returns=\return " \ - endreturns=
\ - "retstmt= " \ - endstmt= \ "cfeescfg=\xrefitem cfeescfg \"Purpose\" \"cFE Executive Services Configuration Parameters\" " \ "cfeevscfg=\xrefitem cfeevscfg \"Purpose\" \"cFE Event Services Configuration Parameters\" " \ "cfetblcfg=\xrefitem cfetblcfg \"Purpose\" \"cFE Table Services Configuration Parameters\" " \ @@ -54,8 +47,8 @@ ALIASES += "event=\xrefitem cfeevents \"Event Message\" \"cFE Even "cfeevstlm=\xrefitem cfeevstlm \"Name\" \"cFE Event Services Telemetry\" " \ "cfesbtlm=\xrefitem cfesbtlm \"Name\" \"cFE Software Bus Telemetry\" " \ "cfetimetlm=\xrefitem cfetimetlm \"Name\" \"cFE Time Services Telemetry\" " \ - "cfecmdmnemonic=\xrefitem cfecmdmnems \"Command Mnemonic(s)\" \"cFE Command Mnemonic Cross Reference\" \b \c " \ - "cfetlmmnemonic=\xrefitem cfetlmmnems \"Telemetry Mnemonic(s)\" \"cFE Telemetry Mnemonic Cross Reference\" \b \c " + "cfecmdmnemonic=\xrefitem cfecmdmnems \"Command Mnemonic(s)\" \"cFE Command Mnemonic Cross Reference\" " \ + "cfetlmmnemonic=\xrefitem cfetlmmnems \"Telemetry Mnemonic(s)\" \"cFE Telemetry Mnemonic Cross Reference\" " OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO BUILTIN_STL_SUPPORT = NO diff --git a/cmake/cfe-usersguide.doxyfile.in b/cmake/cfe-usersguide.doxyfile.in index 9cd8872f8..9ece79b48 100644 --- a/cmake/cfe-usersguide.doxyfile.in +++ b/cmake/cfe-usersguide.doxyfile.in @@ -2,8 +2,10 @@ # Doxygen Configuration options to generate the "cFE Users Guide" #--------------------------------------------------------------------------- -# Start with the common definitions, some of which are extended or overridden here. +# Start with the main page so document ordering is established +INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox +# Common definitions, some of which are extended or overridden here. @INCLUDE = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile PROJECT_NAME = "Core Flight Executive Users Guide" OUTPUT_DIRECTORY = users_guide @@ -15,10 +17,6 @@ GENERATE_LATEX = YES STRIP_FROM_PATH += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs INPUT += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs -# Main page for the users guide -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_usersguide.dox - #PREDEFINED PREDEFINED += @USERGUIDE_PREDEFINED@ diff --git a/cmake/osal-common.doxyfile.in b/cmake/osal-common.doxyfile.in index 44d52c3b0..d6127578f 100644 --- a/cmake/osal-common.doxyfile.in +++ b/cmake/osal-common.doxyfile.in @@ -7,7 +7,7 @@ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English OUTPUT_DIRECTORY = . BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = NO +REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class " \ "The $name widget " \ "The $name file " \ diff --git a/cmake/osalguide.doxyfile.in b/cmake/osalguide.doxyfile.in index c8587a832..431d8cd73 100644 --- a/cmake/osalguide.doxyfile.in +++ b/cmake/osalguide.doxyfile.in @@ -2,21 +2,17 @@ # Doxygen Configuration options to generate the "OSAL API Guide" #--------------------------------------------------------------------------- -# Start with the common definitions, some of which are extended or overridden here. +# Start with the main page so document ordering is established +INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox +# Common definitions, some of which are extended or overridden here. @INCLUDE = @MISSION_BINARY_DIR@/doc/osal-common.doxyfile -PROJECT_NAME = "Core Flight Executive OSAL API Guide" +PROJECT_NAME = "OSAL User's Guide" OUTPUT_DIRECTORY = osalguide GENERATE_LATEX = YES -# Main page for the osal guide -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/osalguide.dox - #PREDEFINED PREDEFINED += @OSALGUIDE_PREDEFINED@ # Bring in the cFE header files for the documentation of the various API calls -INPUT += \ -@MISSION_OSAL_HEADERFILES@ \ -@OSAL_MISC_ADDITION@ \ No newline at end of file +INPUT += @MISSION_OSAL_HEADERFILES@ diff --git a/cmake/sample_defs/cpu1_platform_cfg.h b/cmake/sample_defs/cpu1_platform_cfg.h index be21bc89d..eb49f1f09 100644 --- a/cmake/sample_defs/cpu1_platform_cfg.h +++ b/cmake/sample_defs/cpu1_platform_cfg.h @@ -126,8 +126,8 @@ ** Dictates the size of the SB memory pool. For each message the SB ** sends, the SB dynamically allocates from this memory pool, the memory needed ** to process the message. The memory needed to process each message is msg -** size + msg descriptor(#CFE_SB_BufferD_t). This memory pool is also used -** to allocate destination descriptors (#CFE_SB_DestinationD_t) during the +** size + msg descriptor(CFE_SB_BufferD_t). This memory pool is also used +** to allocate destination descriptors (CFE_SB_DestinationD_t) during the ** subscription process. ** To see the run-time, high-water mark and the current utilization figures ** regarding this parameter, send an SB command to 'Send Statistics Pkt'. @@ -788,7 +788,7 @@ ** log ER Log and critical reset variables. This is 4 of 4 of the memory areas ** that are preserved during a processor reset. ** Note: This area must be sized large enough to hold all of the data -** structures. It should be automatically sized based on the #CFE_ES_ResetData_t +** structures. It should be automatically sized based on the CFE_ES_ResetData_t ** type, but circular dependancies in the headers prevent it from being defined ** this way. ** NOTE: Changing this value changes memory allocation, and may diff --git a/docs/README_dox_templates.txt b/docs/README_dox_templates.txt deleted file mode 100644 index f60a4f261..000000000 --- a/docs/README_dox_templates.txt +++ /dev/null @@ -1,20 +0,0 @@ - -The file "dox_templates.xml" contains some -eclipse templates for some of the doxygen -comment blocks that were specified in the -CFS development standards document. - -For guidance on how to import and use these, -pull up the help contents in Eclipse and -search on "Templates". See the section on -"Importing and exporting code templates" and -then the section on "Creating and editing -code templates" - -Once imported, they all begin with "dox" -Type "dox" then hit "Ctrl-Space" and select -the one you want from the list. Feel free -to edit or tweak these to your preferences. - -These were created under the Windows CDT -v3.3.0 diff --git a/docs/dox_templates.xml b/docs/dox_templates.xml deleted file mode 100644 index 6d6505100..000000000 --- a/docs/dox_templates.xml +++ /dev/null @@ -1,95 +0,0 @@ - \ No newline at end of file diff --git a/docs/src/cfe_es.dox b/docs/src/cfe_es.dox index 15500e9c5..1376969eb 100644 --- a/docs/src/cfe_es.dox +++ b/docs/src/cfe_es.dox @@ -10,24 +10,17 @@ The interfaces to the ES task include the Ground Interface (commands and telemetry) and the Application Programmer Interfaces (APIs). The ES task - interfaces to the OS through the OS Abstraction Layer and interfaces to - the BSP through the BSP Abstraction Layer. + interfaces to the OS through the OS Abstraction Layer (OSAL) and platform + through the Platform Support Package (PSP). - The services provided by the ES task include the Software Reset Service, - Application and Child Task Service, File System Service, Performance Data - Collection Service, Critical Data Store Service, Memory Pool Service, - System Log Service, Shell Command Service and Device Service. Each of these - services provide a full range of features that have been used on past missions. + The functionality provided by the ES task include Software Reset, + Application and Child Task Mangement, Basic File System, Performance Data + Collection, Critical Data Store, Memory Pool, System Log, Shell Command. For additional detail on Executive Services, see the following sections: - Next: \ref cfeesugswreset
+ Next: \ref cfeesugappterm
Up To: \ref cfeesovr **/ @@ -94,7 +74,7 @@ resources are allocated on a per-Application basis. Applications are made up of a Main Task and zero or more Child Tasks. -
Application
+
cFE Application
A 'cFE Application' is an application that is external to the cFE and designed to interface to the cFE through the APIs. It is created through an entry in @@ -102,8 +82,7 @@ by way of the #CFE_ES_START_APP_CC ground command. When referring to one of the five applications internal to the cFE (ES, EVS, - SB, TIME or TBL), the term 'internal application', 'cFE internal application' - or "cFE Core Application" should be used. + SB, TIME or TBL), the term 'Service' or 'Core Application' is typically used. A listing of cFE applications can be acquired by using the #CFE_ES_QUERY_ALL_CC ground command. This listing will include the cFE @@ -147,9 +126,10 @@ The startup script is a text file, written by the user that contains a list of entries (one entry for each application) and is used by the ES application for - automating the startup of applications. The ES application allows the use of a - volatile and nonvolatile startup scripts. The project may utilize zero, one or - two startup scripts. + automating the startup of applications. For a processor reset, ES checks + for the CFE_PLATFORM_ES_VOLATILE_STARTUP_FILE first, and if it doesn't exist + or for a power on reset ES uses the file passed in to #CFE_ES_Main + (typically CFE_PLATFORM_ES_NONVOL_STARTUP_FILE but dependent on the PSP). The fields in a single entry include: @@ -209,21 +189,21 @@ **/ /** - \page cfeesugswreset Software Reset Service + \page cfeesugswreset Software Reset - The ES Software Reset Service provides a command to + The ES Software Reset provides a command to \link #CFE_ES_RESTART_CC reset the cFE \endlink as well as \link #CFE_ES_RESTART_APP_CC resetting individual applications.\endlink Because applications are dependent on the cFE services, it is not possible to reset the cFE without affecting the applications. Therefore, a command to reset the cFE will also reset every application that is running at the time the command is received. - Also part of this service is the Exception and Reset (ER) Log, which has a command for + Also include is the Exception and Reset (ER) Log, which has a command for \link #CFE_ES_WRITE_ER_LOG_CC dumping \endlink or \link #CFE_ES_CLEAR_ER_LOG_CC clearing \endlink the log and telemetry to show the number of entries in the log. In addition to the ER log, the user may find information about the most recent reset in the ES task housekeeping telemetry. - The ES Software Reset Service also provides a command to + The ES Software Reset also provides a command to \link #CFE_ES_SET_MAX_PR_COUNT_CC set the maximum number of processor resets \endlink before ES issues a power-on reset. There is a corresponding 'processor resets' counter in ES housekeeping telemetry that may be \link #CFE_ES_RESET_PR_COUNT_CC reset through another @@ -243,7 +223,7 @@ #CFE_ES_PROCESSOR_RESET. There is a third Reset Type defined in the ES code as #CFE_ES_APP_RESTART which applies only to restarting an individual application and is covered in more detail in the section titled Application - and Child Task Service. + and Child Task. The Reset Subtype is also sent in the ES housekeeping packet and gives more detail about the type of reset that started the execution of the current @@ -275,10 +255,10 @@ A count of the number of entries in the log is present in the ES housekeeping telemetry. This count can be used with the configuration - parameter # CFE_ES_ER_LOG_ENTRIES to calculate the fullness of the log. + parameter #CFE_ES_ER_LOG_ENTRIES to calculate the fullness of the log. The information contained in a single log entry is defined by the - structure #CFE_ES_ERLog_t. + structure CFE_ES_ERLog_t. Next: \ref cfeesugappsrv
Prev: \ref cfeesugresettype
@@ -286,9 +266,9 @@ **/ /** - \page cfeesugappsrv Application and Child Task Service + \page cfeesugappsrv Application and Child Task Management - The ES Application and Child Task Service provide the user with full + The ES Application and Child Task Management provides the user with full control over starting and stopping applications as well as querying information regarding applications, tasks and library routines. @@ -296,7 +276,7 @@ be controlled (started, stopped or deleted) only by the parent application through an API call. - This service provides a way for the user to load a set of library + This provides a way for the user to load a set of library routines, (via the startup script) without starting a corresponding task. See the section related to library routines for more detail. @@ -487,96 +467,48 @@ (cfe_es_startup.scr) also has some detailed information about library routines. - Next: \ref cfeesugloaddevs
+ Next: \ref cfeesugfilesrv
Prev: \ref cfeesugtasklist
Up To: \ref cfeesugappsrv **/ /** - \page cfeesugloaddevs Loading Device Servers + \page cfeesugfilesrv Basic File System - Device Servers have been designed and coded but, as of Build 5.0 of the cFE, - have not been tested. + ES provides minimal functionality to initialize, read, and write + cfe File headers. - Next: \ref cfeesugfilesrv
+ Next: \ref cfeesugperfsrv
Prev: \ref cfeesugloadlibs
Up To: \ref cfeesugappsrv **/ /** - \page cfeesugfilesrv File System Service + \page cfeesugperfsrv Performance Data Collection + The Performance Data Collection provides precise timing + information for each software application similar to + how a logic analyzer can trigger and filter data. - - Next: \ref cfeesugfsdef
- Prev: \ref cfeesugappsrv
- Up To: \ref cfeesovr -**/ - -/** - \page cfeesugfsdef Defining the File Systems - - - - Next: \ref cfeesugfsinit
- Up To: \ref cfeesugfilesrv -**/ - -/** - \page cfeesugfsinit Initializing File Systems - - - - Next: \ref cfeesugfslist
- Prev: \ref cfeesugfsdef
- Up To: \ref cfeesugfilesrv -**/ - -/** - \page cfeesugfslist Listing the File Systems - - - - Next: \ref cfeesugperfsrv
- Prev: \ref cfeesugfsinit
- Up To: \ref cfeesugfilesrv -**/ - -/** - \page cfeesugperfsrv Performance Data Collection Service - - The Performance Data Collection Service is also known as the - Software Timing Analyzer. This service provides precise timing - information for each software application by showing the task - execution time in a waveform style similar to the display on - a logic analyzer. In fact, this service closely models the - operation of a logic analyzer in the way it displays, triggers - and filters the data collected. This service uses passive markers - that are inserted by the development team at key points in the + API calls are inserted by the development team at key points in the code. The basic operation is to start the data collection, wait some amount of time, then send the command to stop the data collection. When the stop command is received, the ES task writes all the data from the buffer to a file. The file can then be - imported to the windows GUI tool that is delivered with every - version of the cFE and displayed on a windows PC. The size of the + imported to analysis tools for viewing. The size of the buffer is configurable through the #CFE_ES_PERF_DATA_BUFFER_SIZE platform configuration parameter. - For more detail refer to the CFE_STA_Integration.doc file and the - Software Timing Analyzer Users Guide.pdf. document. Both files - are located in the cFE/tools/perfutils directory. - Additional information follows:
- Next: \ref cfeesugperfmodes
+ Next: \ref cfeesugperftrig
Prev: \ref cfeesugfilesrv
Up To: \ref cfeesovr **/ @@ -584,68 +516,18 @@ /** \page cfeesugperftrig Performance Data Collection Trigger Masks - The trigger mask is used to tell the Performance Data Collection tool, + The trigger mask is used to control precisely when to start collecting the data. There is a bit in the trigger mask for every marker used in the code. After a start command - is received, the trigger mask is read and dictates when the performance - tool begins storing data in the buffer. + is received, the trigger mask is read and dictates when to + begin storing data in the buffer. If the trigger mask is set to all zeros, then the collection will begin immediately after the start command and continue until a stop command is received. In this case the buffer behaves in a 'circular' manner. - Next: \ref cfeesugperfmodes
- Up To: \ref cfeesugperfsrv -**/ - -/** - \page cfeesugperfmodes Performance Data Collection Modes - - The Performance Data Collection modes are similar to the modes of a - logic analyzer. The user may select a trigger point and 'start' - the trace at the trigger point, 'center' the trace at the trigger - point or 'end' the trace at the trigger point. - Note: The current cFE version does not have a way to set this mode. - The ES software for this version of the cFE always uses the mode to "start the - trace at the trigger point". The cFE FSW DCR 7092 can be used to track the - issue. - - In 'start' mode, with a non-zero trigger mask, the first entry in the - buffer will be the trigger point. The buffer then begins receiving - unfiltered entries. This continues until the buffer becomes full or - until the stop command is received. The result is a buffer that - contains the trigger point and events that occur after the trigger point. - - In 'center' mode, regardless of the trigger point, the buffer begins - receiving unfiltered entries when the start command is received. In - this case the buffer behaves as a circular buffer. When the trigger - point is detected, the collection continues until 'buffer size divided - by 2' entries have been stored or a stop command is received. The - result is a buffer that contains data leading up to the trigger point, - the trigger point itself and data following the trigger point. If the - trigger never occurs and the stop cmd is received, the number of entries - written to the file will correspond to the ES housekeeping telemetry - point named 'Data Count'. - - In 'end' mode, regardless of the trigger point, the buffer begins - receiving unfiltered entries when the start command is received. In - this case the buffer behaves as a circular buffer. The collection - stops immediately after the trigger point is detected. The result - is a buffer that contains data leading up to the trigger point and - the trigger point itself as the last item in the buffer. If the - trigger never occurs and the stop cmd is received, the number of - entries written to the file will correspond to the ES housekeeping - telemetry point named 'Data Count'. - - The 'no trigger' mode can be used to continuously collect data until - the stop command is received. This is done by setting the trigger - mask to all zeros, then sending the start command. The result is a - buffer that contains data up to the stop command. The number of entries - written to the file will correspond to the ES housekeeping telemetry - point named 'DataCount'. - Next: \ref cfeesugperfstart
- Prev: \ref cfeesugperftrig
+ Prev: \ref cfeesugperfsrv
Up To: \ref cfeesugperfsrv **/ @@ -663,7 +545,7 @@ will be displayed in an error event message. Next: \ref cfeesugperfstop
- Prev: \ref cfeesugperfmodes
+ Prev: \ref cfeesugperftrig
Up To: \ref cfeesugperfsrv **/ @@ -684,7 +566,7 @@ in the debug event at the time the stop command is received. Next: \ref cfeesugperfview
- Prev: \ref cfeesugperfmodes
+ Prev: \ref cfeesugperfstart
Up To: \ref cfeesugperfsrv **/ @@ -692,16 +574,8 @@ \page cfeesugperfview Viewing the Collection of Performance Data To view the performance data, the file created as a result of the stop - command must be transferred to the ground and imported into the - Software Timing Analyzer GUI tool. This tool is located in the - cFE/tools/perfutils directory and designed only for Windows - based machines. This GUI must be installed on the windows machine by - way of the installation file named SoftwareTimingAnalyzer.msi. Double - click this file on a windows machine to invoke the installation wizard. - The installation process will place an icon named " Timing Analyzer - on the desktop. Double click the icon and import the file. Refer to the - Software Timing Analyzer Users Guide.pdf. document in the - cFE/tools/perfutils directory for more information. + command must be transferred to the ground and imported into a + viewing tool. See https://github.com/nasa/perfutils-java as an example. Next: \ref cfeesugcdssrv
Prev: \ref cfeesugperfstop
@@ -709,13 +583,13 @@ **/ /** - \page cfeesugcdssrv Critical Data Store Service + \page cfeesugcdssrv Critical Data Store Some missions are required, for health, safety and mission success criteria, to survive Processor Resets. These mission requirements frequently flow down to Attitude Control and/or Command and Data Handling requirements that force an Application developer to design a mechanism for retaining software state information - through a Processor Reset. The cFE provides the Critical Data Store service to + through a Processor Reset. The cFE provides the Critical Data Store to assist the developer in meeting these requirements. The Critical Data Store is an area of memory that is not cleared during a Processor @@ -757,7 +631,7 @@ **/ /** - \page cfeesugmempoolsrv Memory Pool Service + \page cfeesugmempoolsrv Memory Pool Refer to the cFE Application Developers Guide for additional information. @@ -902,7 +776,7 @@ **/ /** - \page cfeesugsyslogsrv System Log Service + \page cfeesugsyslogsrv System Log The System Log is an array of bytes that contains back-to-back printf type messages from applications. The cFE internal applications use this log when @@ -928,9 +802,10 @@ **/ /** - \page cfeesugshellsrv OS Shell Service - + \page cfeesugshellsrv OS Shell + NOTE: This cfe functionality is targeted for deprecation in favor of + optionally including this capability via an application. Next: \ref cfeesugversion
Prev: \ref cfeesugsyslogsrv
@@ -938,9 +813,9 @@ **/ /** - \page cfeesugversion Version Identification Service - + \page cfeesugversion Version Identification + Version information is reported at startup, and upon receipt of a No-op command Next: \ref cfeesugfaq
Prev: \ref cfeesugshellsrv
@@ -948,7 +823,7 @@ **/ /** - \page cfeesugfaq Software Bus Frequently Asked Questions + \page cfeesugfaq Executive Services Frequently Asked Questions diff --git a/docs/src/cfe_evs.dox b/docs/src/cfe_evs.dox index e4ebc707f..b819dd835 100644 --- a/docs/src/cfe_evs.dox +++ b/docs/src/cfe_evs.dox @@ -4,8 +4,13 @@ Event Services (EVS) provides centralized control for the processing of event messages originating from the EVS task itself, other cFE core applications (ES, SB, TIME, and TBL), and from cFE applications. Event messages are asynchronous messages that are used to - inform the operator of a significant event. EVS provides various ways to filter event + inform the operator of a significant event from within the context of a registered + application or core service. EVS provides various ways to filter event messages in order to manage event message generation. + + Note for messages outside the context of a registered appliction (for example early + in app initialization or if registration fails) #CFE_ES_WriteToSysLog can be used + for reporting. For more information on cFE Event Services, see the following sections: @@ -29,21 +34,25 @@ Event messages are software bus messages that contain the following fields:
- The Application Name refers to the Application that issued the event message. - The Event ID is an Application unique number that identifies the event. The - Event Type can be one of four types: DEBUG, INFO, ERROR or CRITICAL. The - Spacecraft ID and Processor ID identify the spacecraft and processor from - which the event was generated. Note that the Spacecraft ID is defined in the - cfe_mission_cfg.h file; The Processor ID is defined in the appropriate - cfe_platform_cfg.h file. The Message is an ASCII text string describing the + The Timestamp corresponds to when the event was generated, in spacecraft time. + The Event Type is one of the following: DEBUG, INFO, ERROR or CRITICAL. + The Spacecraft ID and Processor ID identify the spacecraft and processor + from which the event was generated. Note that the Spacecraft ID is defined in the + cfe_mission_cfg.h file; The Processor ID is defined in the appropriate + cfe_platform_cfg.h file. + The Application Name refers to the Application that issued the event message + as specified on application startup (either startup script or app start command). + The Event ID is an Application unique number that identifies the event. + The Message is an ASCII text string describing the event. Event messages may have parameters associated with the event message. EVS formats the parameters such that they are part of the ASCII text string that make up the event message. @@ -212,7 +221,7 @@ mask 0xFFFF generates one event message and then stops. Note that when the filter counter is reset to zero by command, this will restart the counting and enable n more events to be sent. - Event messages will be filtered until #CFE_EVS_MAX_FILTER_COUNT events of the filtered + Event messages will be filtered until CFE_EVS_MAX_FILTER_COUNT events of the filtered event ID from the application have been received. After this, the filtering will become locked (no more of that event will be received by the ground) until the filter is either reset or deleted by ground command. This is to prevent the counter from rolling over, which would cause @@ -470,6 +479,17 @@ which generates a file containing all of the applications that have registered with EVS and all of the filters that are registered for each application. Note that EVS merely generates the file. The file must be transferred to the ground in order to view it. +
(Q) + Why do I see event messages in my console window? +
  + By default, the events are configured to transmit out a "port" that shows event messages + in the console +
(Q) + What is the difference between event services and the ES System Log +
  + Events are within the context of an App or cFE Service (requires registration with ES). + The system log can be written to outside of the Application or cFE Service context, + for example during application startup to report errors before registration.
diff --git a/docs/src/cfe_sb.dox b/docs/src/cfe_sb.dox index e1dedd2ec..7469d1f2c 100644 --- a/docs/src/cfe_sb.dox +++ b/docs/src/cfe_sb.dox @@ -15,9 +15,8 @@ carefully review the SB statistics and SB memory pool to be sure adequate margin is met on the configurable items. - The cFE software bus differs from earlier versions of the software bus in that it - uses a dynamic protocol and builds its routing table at run-time through the SB - subscribe API's. Also the cFE software bus pipes are created at run-time through + The cFE software bus uses a dynamic protocol and builds its routing table at run-time through + the SB subscribe API's. Also the cFE software bus pipes are created at run-time through the #CFE_SB_CreatePipe API. Because the routing is established, and pipes are created at run-time, it is necessary to have a clear view of the routing details on command. The cFE software bus allows the user to dump the routing table, the pipe table, the @@ -26,27 +25,8 @@ @@ -187,13 +167,13 @@ bus packet sizes. At the time a message is sent, two buffers are allocated from the pool. One for a - buffer descriptor (#CFE_SB_BufferD_t) and one for the size of the packet. Both buffers + buffer descriptor (CFE_SB_BufferD_t) and one for the size of the packet. Both buffers are returned to the pool when the message has been received by all recipients. More precisely, if there is one recipient for a message, the message buffers will be released on the following call to cFE_SB_RcvMsg for the pipe that received the message. Also when subscriptions are received through the subscribe API's, the software bus - allocates a subscription block (#CFE_SB_DestinationD_t) from the pool. The subscription + allocates a subscription block (CFE_SB_DestinationD_t) from the pool. The subscription blocks are returned to the pool if and when the subscription is nullified through a #CFE_SB_Unsubscribe call. @@ -201,7 +181,7 @@ utilization and high water marks relevant to the SB memory pool. This information may be requested by sending the command to dump the SB statistics packet. In addition, the current memory utilization value and the 'unmarked memory' value (#CFE_SB_BUF_MEMORY_BYTES - - peak memory in use) are sent in software bus housekeeping telemetry. The unmarked + minus peak memory in use) are sent in software bus housekeeping telemetry. The unmarked memory value should be monitored regularly to ensure that the value (in bytes) does not continue to decline or approach zero. If this value were to approach zero, there is a possibility that memory requests would fail which may inhibit the sending of a message. @@ -312,25 +292,25 @@ /** \page cfesbugpktseqvals Packet Sequence Values - The software bus populates the packet sequence header field for all telemetry messages that - contain a current subscription. The first time a telemetry message with a new Message ID is - sent, the sequence counter field in the header is set to a value of one. For subsequent + The sequence count behavior depends on if the message is a command type or telemetry type. + + The sequence counter for command messages is not altered by the software bus. + + For telemetry messages sent with the #CFE_SB_SendMsg API, the software bus populates the packet sequence + header field for all messages. The first time a telemetry message is sent with a new Message ID, + the sequence counter field in the header is set to a value of one. For subsequent sends of a message, the sequence counter is incremented by one regardless of the number of destinations for the packet. After a rollover condition the sequence counter will be a value of zero for one instance. The sequence counter is incremented in the #CFE_SB_SendMsg API after all the checks have passed prior to the actual sending of the message. This - includes the parameter checks, the 'no subscribers' check and the memory allocation check. - Note: After passing all checks, the count is incremented regardless of whether the - destinations are enabled or disabled. + includes the parameter checks and the memory allocation check. + Note: The count is incremented regardless of whether there are any subscribers. - Alternatively, the #CFE_SB_PassMsg API can be used to pass a message without altering the - sequence counter provided in the message. This will also not increment the sequence counter - stored by the software bus. This method of message delivery is recommended for situations + For telemetry messages sent with the #CFE_SB_PassMsg API the sequence counter is not incremented. + This method of message delivery is recommended for situations where the sender did not generate the packet, such as a network interface application passing a packet from a remote system to the local software bus. - The sequence counter for command messages is not altered by the software bus. - Next: \ref cfesbugmsgpipeerr
Prev: \ref cfesbugrouting
Up To: \ref cfesbugops @@ -592,6 +572,11 @@ the QOS value to the SB defined #CFE_SB_Default_Qos (QOS.Priority=0,QOS.Reliability=0) will ensure seamless integration when the software bus is expanded to support inter-processor communication. + (Q) + Can I confirm my software bus message was delivered? +   + There is no built in mechanism for confirming delivery (it could span systems). + This could be accomplished by generating a response message from the receiver. diff --git a/docs/src/cfe_tbl.dox b/docs/src/cfe_tbl.dox index fc25a7033..7f91046db 100644 --- a/docs/src/cfe_tbl.dox +++ b/docs/src/cfe_tbl.dox @@ -1,30 +1,28 @@ /** \page cfetblovr cFE Table Services Overview - Applications typically organize sets of their parameters into logical units called tables. These are typically + Applications often organize sets of their parameters into logical units called tables. These are typically constant parameters that can change the behavior of a flight software algorithm and are only intended to be modified by operations personnel. Examples of this would be attitude control gains, sensor - scalefactors, telemetry filter settings, etc. None of the cFE core applications (EVS, SB, ES, TIME - or TBL) use tables. + scalefactors, telemetry filter settings, etc. Table Services (TBL) provides a centralized control of flight software tables. Operations personnel would interact with TBL in order to dump the contents of current tables, load new table images, verify the contents of a table image and manage Critical tables. + None of the cFE core applications (EVS, SB, ES, TIME, or TBL) use tables, and it is possible + to build cFE without Table Services if not needed or an alternative parameter management mechanism + is to be utilized. + For additional detail on Tables and how to manage them, see the following sections: @@ -40,26 +38,26 @@ no longer include the Table Services object module in the CFE-CORE. Even if excluded from the build, the Table Services source and header files will remain in the CFE source tree. - The variable EXCLUDE_CFE_TBL in the setvars.sh file controls whether, or not, CFE Table Services - application is included in the CFE-CORE. The value of EXCLUDE_CFE_TBL must be set equal to TRUE - to cause Table Services to be excluded from the CFE-CORE. Any definition of EXCLUDE_CFE_TBL that - does not set the value equal to TRUE (or no definition at all) will result in the inclusion of cFE - Table Services. The default setvars.sh file contains the line "# EXCLUDE_CFE_TBL=TRUE", but note - that the "#" symbol marks this line as a comment. Remove the "#" symbol to enable the definition - that excludes CFE Table Services. + If EXCLUDE_CFE_TBL is defined (typically in the applicable *_platform_config.h file) Executive + services will not load or shut down table services. Note this option does not effect the build + and link of table services. + + To remove table services from the build completely, remove "tbl" from the CFE_CORE_MODULES + in the cfe/fsw/cfe-core CMakeLists.txt directory (note this option also needs EXCLUDE_CFE_TBL defined + or executive services will try to load it). Removing Table Services reduces the size of the CFE-CORE load file and also reduces the amount of RAM memory required to load the cFE. Each development environment will have unique savings. - The numbers from a test performed using a MCP-750 platform with a GCC compiler are provided for - reference: + The numbers from an example default linux build are as follows: - Size of cFE binary load file with Table Services: 830,969 - Size of cFE binary load file w/o Table services: 721,466 + Size of core cFE binary load file with Table Services: 963K + Size of core cFE binary load file w/o building Table services: 871K - Amount of available RAM after loading cFE with Table Services: 76,513,488 - Amount of available RAM after loading cFE w/o Table Services: 77,151,984 + RAM used after loading cFE with Table Services: 153K + RAM used after loading cFE w/o loading Table Services: 144M - Next: \ref cfetblugmanage
+ Next: \ref cfetblugfaq
+ Prev: \ref cfetblugprocreset
Up To: \ref cfetblovr **/ @@ -115,7 +113,6 @@ the Inactive table image become the Active table image. Next: \ref cfetblugtypes
- Prev: \ref cfetblugdecouple
Up To: \ref cfetblovr **/ @@ -347,7 +344,7 @@ contents of the table are automatically loaded into the table and the Application is notified that the table does not require additional initialization. - Next: \ref cfetblugfaq
+ Next: \ref cfetblugdecouple
Prev: \ref cfetblugtelemetry
Up To: \ref cfetblovr **/ @@ -444,7 +441,7 @@ - Prev: \ref cfetblugprocreset
+ Prev: \ref cfetblugdecouple
Up To: \ref cfetblovr **/ diff --git a/docs/src/cfe_time.dox b/docs/src/cfe_time.dox index b68e8e7c8..b60e37f70 100644 --- a/docs/src/cfe_time.dox +++ b/docs/src/cfe_time.dox @@ -125,9 +125,9 @@ CCSDS Unsegmented Time Code (CUC) which includes 4 bytes of seconds, and 4 bytes of subseconds, where a subsecond is equivalent to 1/(2^32) seconds. The system time structure is used by TIME to store current time, time at the tone, time since the - tone, the MET, the STCF and command arguments for time adjustments. Note that only + tone, the MET, the STCF and command arguments for time adjustments. Note that typically the 32 bits of seconds and the upper 16 bits of subseconds are used for time stamping - CCSDS packets. + Software bus messages, but this is dependent on the underlying defintion. The system time structure is defined as follows: @@ -757,10 +757,12 @@ \page cfetimeugadjust Adjusting Time The TIME Server includes commands to set the STCF, Leap Seconds, - and Validity state. The STCF should be set by the jam command, - and fine tuned using the delta adjust. TIME provides the ability - to command a one time adjustment (add or subtract) to the current - STCF. In addition there is a 1Hz adjustment (add or subtract) + and Validity state. The STCF should be set implicity using the + #CFE_TIME_SET_TIME_CC or explicitly using #CFE_TIME_SET_STCF_CC. + TIME provides the ability to command a one time adjustment + (#CFE_TIME_ADD_ADJUST_CC and #CFE_TIME_SUB_ADJUST_CC) + to the current STCF. In addition there is a 1Hz adjustment + (#CFE_TIME_ADD_1HZ_ADJUSTMENT_CC and #CFE_TIME_SUB_1HZ_ADJUSTMENT_CC) that can be made to the STCF to compensate for oscillator drift. Mission specific ground correlation should be used to assist in determining the proper values to use. The Leap Seconds should be diff --git a/docs/src/cfe_usersguide.dox b/docs/src/cfe_usersguide.dox deleted file mode 100644 index becd3b76d..000000000 --- a/docs/src/cfe_usersguide.dox +++ /dev/null @@ -1,67 +0,0 @@ -/** - \page cfeusersguide cFE User's Guide - - - -**/ - -/** - \page cfeugmsgs Inter-Application Messages - -**/ - -/** - \page cfeugfiles File Systems and cFE Files - -**/ - diff --git a/docs/src/ddd_main.dox b/docs/src/ddd_main.dox index 08251764f..0fe1b4769 100644 --- a/docs/src/ddd_main.dox +++ b/docs/src/ddd_main.dox @@ -2,11 +2,6 @@ \mainpage Core Flight Executive Documentation