diff --git a/README.md b/README.md index fc7e8f1ec..9dbc32c99 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,30 @@ The detailed cFE user's guide can be viewed at + ### Development Build: v6.8.0-rc1+dev436 - Adds a local definition of SOFTWARE_BIG/LITTLE_BIT_ORDER directly inside cfe_endian.h to provide a compatible symbol for apps that still require this. This allows CFE to build and run successfully when OSAL stops providing this in `common_types.h`. diff --git a/cmake/Makefile.sample b/cmake/Makefile.sample index c1466e7d3..db232e35c 100644 --- a/cmake/Makefile.sample +++ b/cmake/Makefile.sample @@ -141,7 +141,7 @@ test: 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 + genhtml $(O)/$(ARCH)/coverage_total.info --branch-coverage --output-directory $(O)/$(ARCH)/lcov @/bin/echo -e "\n\nCoverage Report Link: file:$(CURDIR)/$(O)/$(ARCH)/lcov/index.html\n" doc: diff --git a/cmake/sample_defs/cpu1_msgids.h b/cmake/sample_defs/cpu1_msgids.h index aa9a52098..0da698f15 100644 --- a/cmake/sample_defs/cpu1_msgids.h +++ b/cmake/sample_defs/cpu1_msgids.h @@ -18,22 +18,23 @@ ** limitations under the License. */ -/****************************************************************************** -** File: cfe_msgids.h -** -** Purpose: -** This header file contains the Message Id's for messages used by the -** cFE core. -** -** Author: R.McGraw/SSI -** -** Notes: -** This file should not contain messages defined by cFE external -** applications. -** -******************************************************************************/ -#ifndef _cfe_msgids_ -#define _cfe_msgids_ +/** + * @file + * + * Purpose: + * This header file contains the Message Id's for messages used by the + * cFE core. + * + * Author: R.McGraw/SSI + * + * Notes: + * This file should not contain messages defined by cFE external + * applications. + * + */ + +#ifndef CPU1_MSGIDS_H +#define CPU1_MSGIDS_H /* ** Includes @@ -129,4 +130,4 @@ #define CFE_SB_ONESUB_TLM_MID CFE_PLATFORM_TLM_MID_BASE + CFE_MISSION_SB_ONESUB_TLM_MSG /* 0x080E */ #define CFE_ES_MEMSTATS_TLM_MID CFE_PLATFORM_TLM_MID_BASE + CFE_MISSION_ES_MEMSTATS_TLM_MSG /* 0x0810 */ -#endif +#endif /* CPU1_MSGIDS_H */ diff --git a/cmake/sample_defs/cpu1_platform_cfg.h b/cmake/sample_defs/cpu1_platform_cfg.h index 49bf9ed4c..ee4c5d478 100644 --- a/cmake/sample_defs/cpu1_platform_cfg.h +++ b/cmake/sample_defs/cpu1_platform_cfg.h @@ -18,23 +18,23 @@ ** limitations under the License. */ -/****************************************************************************** -** File: cfe_platform_cfg.h -** -** Purpose: -** This header file contains the platform configuration parameters. -** -** Notes: -** The impact of changing these configurations from their default value is -** not yet documented. Changing these values may impact the performance -** and functionality of the system. -** -** Author: R.McGraw/SSI -** -******************************************************************************/ +/** + * @file + * + * Purpose: + * This header file contains the platform configuration parameters. + * + * Notes: + * The impact of changing these configurations from their default value is + * not yet documented. Changing these values may impact the performance + * and functionality of the system. + * + * Author: R.McGraw/SSI + * + */ -#ifndef _cfe_platform_cfg_ -#define _cfe_platform_cfg_ +#ifndef CPU1_PLATFORM_CFG_H +#define CPU1_PLATFORM_CFG_H /** ** \cfeescfg Default virtual path for persistent storage @@ -1708,4 +1708,4 @@ */ #define CFE_PLATFORM_ES_STARTUP_SCRIPT_TIMEOUT_MSEC 1000 -#endif /* _cfe_platform_cfg_ */ +#endif /* CPU1_PLATFORM_CFG_H */ diff --git a/cmake/sample_defs/sample_mission_cfg.h b/cmake/sample_defs/sample_mission_cfg.h index e0ecdca87..319587389 100644 --- a/cmake/sample_defs/sample_mission_cfg.h +++ b/cmake/sample_defs/sample_mission_cfg.h @@ -18,24 +18,24 @@ ** limitations under the License. */ -/****************************************************************************** -** File: cfe_mission_cfg.h -** -** Purpose: -** This header file contains the mission configuration parameters and -** typedefs with mission scope. -** -** Notes: -** The impact of changing these configurations from their default value is -** not yet documented. Changing these values may impact the performance -** and functionality of the system. -** -** Author: R.McGraw/SSI -** -******************************************************************************/ - -#ifndef _cfe_mission_cfg_ -#define _cfe_mission_cfg_ +/** + * @file + * + * Purpose: + * This header file contains the mission configuration parameters and + * typedefs with mission scope. + * + * Notes: + * The impact of changing these configurations from their default value is + * not yet documented. Changing these values may impact the performance + * and functionality of the system. + * + * Author: R.McGraw/SSI + * + */ + +#ifndef SAMPLE_MISSION_CFG_H +#define SAMPLE_MISSION_CFG_H /** ** \cfesbcfg Maximum SB Message Size @@ -65,7 +65,6 @@ ** format. This avoids having to modify each individual caller ** when the default choice is changed. ** -** ** \par Limits ** if CFE_MISSION_TIME_CFG_DEFAULT_TAI is defined as true then CFE_MISSION_TIME_CFG_DEFAULT_UTC must be ** defined as false. @@ -82,7 +81,6 @@ ** The following definition enables the use of a simulated time at ** the tone signal using a software bus message. ** -** ** \par Limits ** Not Applicable */ @@ -131,7 +129,6 @@ ** ** Note: units are in micro-seconds ** -** ** \par Limits ** 0 to 999,999 decimal */ @@ -421,7 +418,6 @@ ** anticipated to be reasonably small (i.e. tens, not hundreds). Large ** values have not been tested. ** -** */ #define CFE_MISSION_ES_POOL_MAX_BUCKETS 17 @@ -562,4 +558,4 @@ */ #define CFE_MISSION_ES_CDS_MAX_FULL_NAME_LEN (CFE_MISSION_ES_CDS_MAX_NAME_LENGTH + CFE_MISSION_MAX_API_LEN + 4) -#endif /* _cfe_mission_cfg_ */ +#endif /* SAMPLE_MISSION_CFG_H */ diff --git a/cmake/sample_defs/sample_perfids.h b/cmake/sample_defs/sample_perfids.h index 3a99b612c..f5e2d8427 100644 --- a/cmake/sample_defs/sample_perfids.h +++ b/cmake/sample_defs/sample_perfids.h @@ -18,24 +18,24 @@ ** limitations under the License. */ -/* -** File: cfe_perfids.h -** -** Purpose: This file contains the cFE performance IDs -** -** Design Notes: -** Each performance id is used to identify something that needs to be -** measured. Performance ids are limited to the range of 0 to -** CFE_MISSION_ES_PERF_MAX_IDS - 1. Any performance ids outside of this range -** will be ignored and will be flagged as an error. Note that -** performance ids 0-31 are reserved for the cFE Core. -** -** References: -** -*/ - -#ifndef _cfe_perfids_ -#define _cfe_perfids_ +/** + * @file + * + * Purpose: This file contains the cFE performance IDs + * + * Design Notes: + * Each performance id is used to identify something that needs to be + * measured. Performance ids are limited to the range of 0 to + * CFE_MISSION_ES_PERF_MAX_IDS - 1. Any performance ids outside of this range + * will be ignored and will be flagged as an error. Note that + * performance ids 0-31 are reserved for the cFE Core. + * + * References: + * + */ + +#ifndef SAMPLE_PERFIDS_H +#define SAMPLE_PERFIDS_H #define CFE_MISSION_ES_PERF_EXIT_BIT 31 /**< \brief bit (31) is reserved by the perf utilities */ @@ -58,4 +58,4 @@ /** \} */ -#endif /* _cfe_perfids_ */ +#endif /* SAMPLE_PERFIDS_H */ diff --git a/cmake/target/inc/target_config.h b/cmake/target/inc/target_config.h index 495036318..554b2a2c1 100644 --- a/cmake/target/inc/target_config.h +++ b/cmake/target/inc/target_config.h @@ -19,10 +19,7 @@ */ /** - * \file target_config.h - * - * Created on: Dec 12, 2014 - * Created by: joseph.p.hickey@nasa.gov + * @file * * Defines structures for the global system-wide configuration data. * These structures can be accessed at runtime and are an alternative to @@ -31,8 +28,8 @@ * code becomes more portable. */ -#ifndef TARGET_CONFIG_H_ -#define TARGET_CONFIG_H_ +#ifndef TARGET_CONFIG_H +#define TARGET_CONFIG_H #include "common_types.h" #include "cfe_psp_configdata.h" @@ -213,4 +210,4 @@ typedef const struct */ extern Target_ConfigData GLOBAL_CONFIGDATA; -#endif /* TARGET_CONFIG_H_ */ +#endif /* TARGET_CONFIG_H */ diff --git a/docs/README_functionaltest.md b/docs/README_functionaltest.md index 027e9f757..b65a3f439 100644 --- a/docs/README_functionaltest.md +++ b/docs/README_functionaltest.md @@ -29,10 +29,10 @@ cases. It also must be loaded after `cfe_assert`. To execute tests at startup, the following lines can be added to `cfe_es_startup.scr` on the designated test target: - CFE_LIB, /cf/cfe_assert.so, CFE_Assert_LibInit, ASSERT_LIB, 0, 0, 0x0, 0; - CFE_APP, /cf/cfe_testrunner.so, CFE_TestRunner_AppMain, TESTRUN_APP, 100, 16384, 0x0, 0; - CFE_LIB, /cf/cfe_testcase.so, CFE_Test_Init, CFETEST_LIB, 0, 0, 0x0, 0; - CFE_LIB, /cf/psp_test.so, PSP_Test_Init, PSPTEST_LIB, 0, 0, 0x0, 0; + CFE_LIB, cfe_assert, CFE_Assert_LibInit, ASSERT_LIB, 0, 0, 0x0, 0; + CFE_APP, cfe_testrunner, CFE_TR_AppMain, TESTRUN_APP, 100, 16384, 0x0, 0; + CFE_LIB, cfe_testcase, CFE_Test_Init, CFETEST_LIB, 0, 0, 0x0, 0; + CFE_LIB, psp_test, PSP_Test_Init, PSPTEST_LIB, 0, 0, 0x0, 0; It is important that `cfe_assert` is loaded first, as all other test libraries depend on symbols provided in this library. The order of loading other test cases should not diff --git a/docs/cFE Application Developers Guide.md b/docs/cFE Application Developers Guide.md index 28ae5a10f..4e3c37892 100644 --- a/docs/cFE Application Developers Guide.md +++ b/docs/cFE Application Developers Guide.md @@ -313,20 +313,20 @@ directory is described as a note under each folder. ![](.//media/cFE_Application_Developers_Guide_image6.png) -Each cFE core component is itself a modular entity, all of which work together to form the +Each cFE core component is itself a modular entity, all of which work together to form the complete cFE core executive. These modules are all contained under the `modules` subdirectory: | **Directory** | **Content** | |:------------------------|:------------------------------------------------------------------------------------------------------------------ | | `modules/core_api/` | Contains the public interface definition of the complete CFE core - public API/headers only, no implementation | | `modules/core_private/` | Contains the inter-module interface definition of the CFE core - internal API/headers only, no implementation | -| `modules/es/` | Implementation of the Executive Services (ES) core module - provides app and task management | -| `modules/evs/` | Implementation of the Event Services (EVS) core module - manages sending of events on behalf of other apps | -| `modules/fs/` | Implementation of the File Services (FS) core module - defines file-related functions | -| `modules/msg/` | Implementation of the Message (MSG) core module - defines message header manipulation/access routines | -| `modules/resourceid/` | Implementation of the Resource ID core module - maniplation/access of system resource IDs (AppID, PipeID, etc.) | -| `modules/sb/` | Implementation of the Software Bus (SB) core module - sends messages between applications | -| `modules/tbl/` | Implementation of the Table Services (TBL) core module - manages runtime tables | +| `modules/es/` | Implementation of the Executive Services (ES) core module - provides app and task management | +| `modules/evs/` | Implementation of the Event Services (EVS) core module - manages sending of events on behalf of other apps | +| `modules/fs/` | Implementation of the File Services (FS) core module - defines file-related functions | +| `modules/msg/` | Implementation of the Message (MSG) core module - defines message header manipulation/access routines | +| `modules/resourceid/` | Implementation of the Resource ID core module - maniplation/access of system resource IDs (AppID, PipeID, etc.) | +| `modules/sb/` | Implementation of the Software Bus (SB) core module - sends messages between applications | +| `modules/tbl/` | Implementation of the Table Services (TBL) core module - manages runtime tables | | `modules/time/` | Implementation of the Time Services (TIME) core module - manages timing and synchronization | **NOTE**: The modules contained here constitute the "reference" implementation of each module. The CMake build system also permits advanced users @@ -357,7 +357,7 @@ Each module directory is in turn divided into subdirectories as follows: In order for applications to use and call cFE service functions, the developer must include the appropriate header files in their source -code. +code. The cFE header files are split into several parts/sections, allowing application/libraries to individually select the parts they need. The @@ -373,11 +373,11 @@ naming convention is as follows: In general the files are scoped such that an application/library should only need to include the information it actually needs to use for the task it performs. For instance, if a tool needs to interpret a data file generated by CFE ES, only the `cfe_es_extern_typedefs.h` file should be required. To send commands or interpret telemetry, the -`cfe_es_msg.h` may be used. If a library builds upon data types or extends functions from the ES API, then the +`cfe_es_msg.h` may be used. If a library builds upon data types or extends functions from the ES API, then the `cfe_es_api_typedefs.h` header may be used. An "unqualified" header file (with no extra suffix) provides the complete runtime API definition for the component. -This includes all API function prototypes and is intended for use in C source files. The following API header files +This includes all API function prototypes and is intended for use in C source files. The following API header files are provided by cFE: | **Filename** | **Contents** | @@ -392,11 +392,11 @@ are provided by cFE: | cfe_time.h | cFE Time Service Interface | -**NOTE**: The files listed above provide function prototypes and are intended to be used by C source files +**NOTE**: The files listed above provide function prototypes and are intended to be used by C source files that contain code which needs to invoke the function(s) prototyped within them. When referencing the data types or macros from another header file, the targeted/qualified header should be used instead. -As a rule of thumb, files listed in the first table (with suffix) should be included from within other +As a rule of thumb, files listed in the first table (with suffix) should be included from within other headers, while files listed in the second table (without suffix) should be used by source files. Finally, to simplify application headers, a single "all-inclusive" cFE header is also provided: @@ -488,12 +488,12 @@ deciding on whether to create multiple Applications versus a single Application with multiple Tasks, the Application Developer should keep in mind these facts: -- When the Application exits it is the responsiabilty of the +- When the Application exits it is the responsiabilty of the Main Task to safely stop all of its Child Tasks. - If the Main Task of an Application is stopped, either through detection of an exception or via command, all Child Tasks are also - forcibly stopped in an unsafe manner. + forcibly stopped in an unsafe manner. Child Tasks can be useful in both "Software Only" and "Hardware Servicing" applications. @@ -501,12 +501,12 @@ applications. ## 4.2 Best Practices ### 4.2.1 cFS Application Template -Applications designed to interface with the cFE should follow standard templates. +Applications designed to interface with the cFE should follow standard templates. Reference sample_app on Github for “live” example. | **Directory** | **Descriptions** | |:--------------------------------------|:-------------------------------------------------------------------------------------------------------------| -| fsw/ | All components which are used on/deployed to the actual target or define the interface to those components | +| fsw/ | All components which are used on/deployed to the actual target or define the interface to those components | | fsw/inc/ | Public/Interface headers for the component | | fsw/src/ | Source files and private headers for the component | | tables/ | Example/Initial table definitions | @@ -525,7 +525,7 @@ Reference sample_app on Github for “live” example. In addition to showing the standard structure of a cFS application, the sample_app also demonstrates how to interface with cFS libraries and table -services. +services. ### 4.2.2 Avoid "Endian-ness" Dependencies @@ -558,7 +558,7 @@ Examples of items that must be shared with other Applications include Message IDs and Message data structures. Inter- application communication should rely on the published interfaces described above (generally using the software bus) rather than directly calling functions internal to another -application. +application. Examples of items that do not need to be shared with other Applications include Table IDs, Table data structures, Event IDs and Pipe IDs. Tables are not @@ -595,9 +595,9 @@ found in the OSAL Library API documentation. ## 5.1 Application Registration -All cFE Applications must register immediately with ES when started. -This is accomplished with the CFE_ES_RegisterApp function and it -should be the first function called by a cFE Application's main task. +All cFE Applications are now automatically registered with ES before the +user-specified entry point is invoked. There is no specific registration +function to invoke as was necessary in older versions of cFE. ## 5.2 Application Names and IDs @@ -625,10 +625,11 @@ additional threads that are spawned by this thread are referred to as Child Tasks. There are a handful of functions provided by the Executive Services for controlling Child Tasks. The first is CFE_ES_CreateChildTask. This function spawns a Child Task that is -"owned" by the Main Task. Each of the Child Tasks must then register -with ES via the CFE_ES_RegisterChildTask function. The remaining -functions, CFE_ES_DeleteChildTask, CFE_ES_SuspendChildTask and -CFE_ES_ResumeChildTask can control the existence and execution of the +"owned" by the Main Task. This child task is automatically registered +with ES before invoking the entry point. + +The remaining functions, CFE_ES_DeleteChildTask, CFE_ES_SuspendChildTask +and CFE_ES_ResumeChildTask can control the existence and execution of the Child Task. All of these functions require the task ID that is returned by the CFE_ES_CreateChildTask function in order to identify the Child Task. Note that Child Tasks can only be created from an Application's @@ -736,7 +737,7 @@ osobjtab.c file for the processor. A binary semaphore can be created using the OS_BinSemCreate function. Upon success, the OS_BinSemCreate function sets the sem_id parameter to the ID of the newly-created resource. This ID is used in all other functions that use -the binary semaphore. +the binary semaphore. ``` int32 OS_BinSemCreate(uint32 *xxx_SEM_ID, const char *xxx_SEM_NAME, @@ -780,10 +781,10 @@ implement a kind of handshake between its main task and its child task. ### 5.7.3.1 Counting Semaphore Functions -A counting semaphore can be created using the OS_CountSemCreate function. +A counting semaphore can be created using the OS_CountSemCreate function. Upon success, the OS_CountSemCreate function sets the sem_id parameter to the ID of the newly-created resource. This ID is used in all other functions that -use the binary semaphore. +use the binary semaphore. ``` int32 OS_CountSemCreate(uint32 *xxx_SEM_ID, const char *xxx_SEM_NAME, @@ -895,7 +896,7 @@ to the OSAL Library API). ## 5.8 Interrupt Handling -OSAL interrupt handling functions have been deprecated due to +OSAL interrupt handling functions have been deprecated due to platform dependencies, incomplete testing, and incomplete implementaion No longer supporting abstracted interrupt handling API from OSAL. Could @@ -1051,7 +1052,7 @@ into a working image in the Application.  An example of how to use the CDS is shown below: -``` +```c FILE: "sample_task.h": /* Define the structure for the data stored in my Critical Data Store */ @@ -1078,7 +1079,7 @@ typedef struct #define SAMPLE_CDS_NAME "CDS" ``` -``` +```c FILE: "sample_task.c": SAMPLE_TaskData_t SAMPLE_TaskData; @@ -1097,7 +1098,7 @@ int32 SAMPLE_TaskInit(void) { /* Critical Data Store already existed, we need to get a */ /* copy of its current contents to see if we can work use it */ - Status = CFE_ES_RestoreFromCDS(&SAMPLE_MyCDSDataType_t, + Status = CFE_ES_RestoreFromCDS(&SAMPLE_MyCDSDataType_t, SAMPLE_TaskData.MyCDSHandle); if (Status == CFE_SUCCESS) @@ -1165,13 +1166,13 @@ void SAMPLE_TaskMain(void) ### 5.10.4 Standard CRC Calculations There are many Applications that require a validation of received data or of -data in memory. This is usually done by a Cyclic Redundancy Check (CRC). +data in memory. This is usually done by a Cyclic Redundancy Check (CRC). There are many different ways to calculate a CRC. To help ensure that the calculation is done consistently for a mission, the Executive Services provides an API for a CRC calculation that can be used by all Applications on a mission. This function looks like the following: -``` +```c uint32 CFE_ES_CalculateCRC(void *pData, uint32 DataLength, uint32 InputCRC, uint32 TypeCRC); ``` @@ -1269,9 +1270,9 @@ main execution loop. Applications can track performance of multiple sections of code, but must define a unique "performance id" (or "perfid") for each segment of code to monitor. Applications typically define these perfids in their xx_mission_cfg.h file. A common pattern for performance monitoring is -shown below. +shown below. -``` +```c FILE: xx_app.c void XX_AppMain(void) @@ -1280,9 +1281,6 @@ void XX_AppMain(void) CFE_SB_Buffer_t *SBBufPtr; int32 Result = CFE_SUCCESS; - /* Register application */ - Result = CFE_ES_RegisterApp(); - /* Performance Log (start time counter) */ CFE_ES_PerfLogEntry(XX_APPMAIN_PERF_ID); @@ -1326,7 +1324,7 @@ void XX_AppMain(void) RunStatus = CFE_ES_RunStatus_APP_ERROR; } } - +} ``` While outside the scope of this documentation, an external post processing tool @@ -1469,7 +1467,7 @@ the cFE of pipes that it requires to receive data. The Application performs this request by calling the CFE_SB_CreatePipe API. The following is a brief example of how this is accomplished: -``` +```c FILE: sample_app.h ... @@ -1484,9 +1482,9 @@ typedef struct CFE_SB_PipeId_t SAMPLE_Pipe_1; /* Variable to hold Pipe ID (i.e.- Handle) */ ... } SAMPLE_AppData_t; - -``` ``` + +```c FILE: sample_app.c SAMPLE_AppData_t; SAMPLE_AppData; @@ -1501,10 +1499,9 @@ SAMPLE_AppData_t; SAMPLE_AppData; SAMPLE_PIPE_1_NAME); /* Name of Pipe */ ... } - ``` -In this example, the Developer has created a Pipe, called "SAMPLE_PIPE_1" +In this example, the Developer has created a Pipe, called `SAMPLE_PIPE_1` with a depth of 10. The Pipe name shall be at least one character and no more than OS_MAX_API_NAME characters long. Developers should prefix their Pipe names with the Application's abbreviated name, because Pipe names will @@ -1522,8 +1519,7 @@ important when using other SB API functions. It is important to realize that the Pipe is not multi-thread safe. Therefore, it is illegal for another thread, even one from the same Application, to attempt to receive data from the created pipe. If multiple threads require access -to messages, each thread needs to create their own pipe and make their -own message subscriptions. +to messages, each thread needs to create their own pipe and make their own message subscriptions. ## 6.2.1 Deleting Software Bus Pipes @@ -1531,7 +1527,7 @@ If an Application no longer requires a Pipe, it can delete the Pipe by calling the CFE_SB_DeletePipe API. This API is demonstrated as follows: -``` +```c FILE: sample_app.c { @@ -1559,7 +1555,7 @@ Once an Application has created a Pipe, it can begin to request data be put into that Pipe. This process is referred to a SB Message Subscription. An example of this process can be seen below: -``` +```c FILE: sample_msgids.h ... @@ -1567,7 +1563,7 @@ FILE: sample_msgids.h #define SAMPLE_CMDID_1 (0x0123) ... ``` -``` +```c FILE: sample_app.h ... @@ -1583,7 +1579,7 @@ typedef struct } SAMPLE_AppData_t; ``` -``` +```c FILE: sample_app.c SAMPLE_AppData_t SAMPLE_AppData; @@ -1636,7 +1632,7 @@ If an Application no longer wishes to receive an SB Message that it had previously subscribed to, it can selectively unsubscribe to specified SB Message IDs. The following is a sample of the API to accomplish this: -``` +```c { int32 Status; @@ -1659,7 +1655,7 @@ memory for it (instantiate it), initialize it with the appropriate SB Message Header information and fill the rest of the structure with appropriate data. An example of this process can be seen below: -``` +```c FILE: sample_msgids.h ... @@ -1668,7 +1664,7 @@ FILE: sample_msgids.h ``` -``` +```c FILE: sample_app.h /* @@ -1700,7 +1696,7 @@ typedef struct ... } SAMPLE_AppData_t; ``` -``` +```c FILE: sample_app.c SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */ @@ -1744,7 +1740,7 @@ secondary header structures. The secondary header structures are shown below. Note that all messages must have a secondary header, a message containing just a CFE_MSG_Message_t is invalid per the CCSDS standard. -``` +```c typedef struct { @@ -1773,7 +1769,7 @@ sizeof(CFE_MSG_CommandHeader_t) and sizeof(CFE_MSG_TelemetryHeader_t) respective It is important to note that some API calls require the presence of a particular header type and will return an error if the other header type -is present instead. The following section provides more detail. +is present instead. The following section provides more detail. ### 6.5.2 Setting Message Header Information @@ -1805,7 +1801,7 @@ The preference is to use CFE_MSG_SetSize and actual packet structure information when available. ### 6.5.2.1 Modifying Command Message Header Information -The most common update for command messages is to set the command code. +The most common update for command messages is to set the command code. This is done through the CFE_MSG_SetFcnCode() API call. This code is used to distinguish between multiple commands that share a Message ID. It is common practice for an application to have a single "CMD_MID" to capture @@ -1856,7 +1852,7 @@ After an SB message has been created (see Section 6.5) and its contents have been set to the appropriate values, the application can then send the message on the SB. An example of this is shown below: -``` +```c FILE: sample_app.c SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */ @@ -1877,14 +1873,15 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */ CFE_SB_TransmitMsg(&SAMPLE_APP_Data.HkTlm.TlmHeader.Msg, true); ... } -``` +``` + ## 6.7 Receiving Software Bus Messages To receive a SB Message, an application calls CFE_SB_ReceiveBuffer. Since most applications are message-driven, this typically occurs in an application's main execution loop. An example of this is shown below. -``` +```c FILE: sample_app.h typedef struct @@ -1894,7 +1891,7 @@ typedef struct ... } SAMPLE_AppData_t; ``` -``` +```c FILE: sample_app.c { @@ -1937,7 +1934,7 @@ a CFE_SB_NO_MESSAGE status code. After a message is received, the SB Message Header accessor functions (as described in Section 6.5.3) should be used to identify the message so that -the application can react to it appropriately. +the application can react to it appropriately. ## 6.8 Improving Message Transfer Performance for Large Messages @@ -1951,7 +1948,7 @@ copy is too time consuming, the Developer can choose to utilize the "Zero Copy" protocol. The application can request a buffer from SB utilizing -CFE_SB_ZeroCopyGetPtr, then write the message data directly to the +`CFE_SB_AllocateMessageBuffer`, then write the message data directly to the buffer that can be sent directly (without a copy) by SB. Once an Application has formatted and filled the SB buffer with the @@ -1963,14 +1960,14 @@ calls the CFE_SB_TransmitBuffer API.** Applications should not assume the SB Buffer pointer is accessible once the buffer has been sent. -If an Application has called the CFE_SB_ZeroCopyGetPtr API call and +If an Application has called the `CFE_SB_AllocateMessageBuffer` API call and then later determines that it is not going to send the SB Message, it shall free the allocated buffer by calling the -CFE_SB_ZeroCopyReleasePtr API. +`CFE_SB_ReleaseMessageBuffer` API. An example of the "Zero Copy" protocol is shown below: -``` +```c FILE: app_msgids.h ... @@ -2019,8 +2016,8 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */ /* ** Get a SB Message block of memory and initialize it */ - SAMPLE_AppData.BigPktBuf = (SAMPLE_BigPkt_Buffer_t *)CFE_SB_ZeroCopyGetPtr(sizeof(SAMPLE_BigPkt_t), - &BufferHandle); + SAMPLE_AppData.BigPktBuf = (SAMPLE_BigPkt_Buffer_t *)CFE_SB_AllocateMessageBuffer(sizeof(SAMPLE_BigPkt_t)); + CFE_MSG_Init(SAMPLE_AppData.BigPktBuf->Pkt.TlmHeader.Msg, SAMPLE_BIG_TLM_MID, sizeof(SAMPLE_AppData.BigPktBuf->Pkt); @@ -2036,14 +2033,14 @@ SAMPLE_AppData_t SAMPLE_AppData; /* Instantiate Task Data */ /* SAMPLE_AppData.BigPktBuf is no longer a valid pointer */ ... } -``` +```c ## 6.9 Best Practices for using Software Bus The following are recommended "best practices" for applications using EVS. 1. Applications should use the Software Bus for all communication with other applications. -2. Pipe depth and message limits are dependent on the entire software system. +2. Pipe depth and message limits are dependent on the entire software system. Consider both the receiving application and any sending application(s) when choosing those limits. 3. Applications shall always use AB API functions to read or manipulate the SB @@ -2051,7 +2048,7 @@ The following are recommended "best practices" for applications using EVS. 4. Applications should maintain a command counter and a command error counter in housekeeping telemetry. 5. Applications should support a "No-operation" command and a "Reset Counters" - command. + command. 6. Every application should have at least one pipe. # 7. Event Service Interface @@ -2072,7 +2069,7 @@ Child Task. Event messages are implemented as software bus messages. It is important for developers to note that Event Messages are not automatically sent as telemetry. A Telemetry Output (or equivalent) application must be -configured to downlink event messages if they need to be sent as telemetry. +configured to downlink event messages if they need to be sent as telemetry. ## 7.2 Event Types @@ -2129,7 +2126,7 @@ the short format does not include the text string portion of the message. Because of this, it is very important that Event Messages IDs be unique across an Application, including all Child Tasks. Unique message IDs will allow a message to be understood even in "short format" when the text -string is unavailable to provide supplemental information. +string is unavailable to provide supplemental information. ## 7.4 Event Service Registration @@ -2137,7 +2134,7 @@ Applications must register with the EVS in order to use cFE event services. If an application has registered with EVS, then all of its Child Tasks are also registered and able to send Event Messages. cFE libraries however are not able to register for EVS or send Event -Messages. +Messages. Event services include the sending and filtering of event messages. EVS registration is performed using the CFE_EVS_Register @@ -2384,7 +2381,7 @@ CFE_EVS_Unregister (); The following are recommended "best practices" for applications using EVS. 1. Event Message IDs should be unique across an application so that an - event can be identified even without text. + event can be identified even without text. 2. The "No Operation" command in an application should send an Information Event Message with the application's version number. 3. Abide by the guidance in Section 7.5.1 when creating event message @@ -2396,7 +2393,7 @@ The following are recommended "best practices" for applications using EVS. 5. Ensure that adequate debug messages are left in an application to allow debugging to occur in flight if necessary. When an application is complete, all remaining debug "printf" statements should be either - removed or converted to Debug event messages. + removed or converted to Debug event messages. # 8. Table Service Interface @@ -2511,7 +2508,7 @@ they wish to have created and the cFE responds with an Application unique Table Handle. An example of this process is shown in Section 8.5.1. It should be noted that the Table Services automatically makes the table name -processor specific by prepending the Application name to the given table name. +processor specific by prepending the Application name to the given table name. Therefore, after the above example is executed, Table Services would have added a table with the name “SAMPLE.MyTableName” to the Table Registry. If an Application is sharing a Table that is created by another Application, @@ -2781,13 +2778,13 @@ xx | |----xx_tbl.c | |----tables - | |----xx_table1.c + | |----xx_table1.c | |----platform_inc - |----xx_platform_cfg.h + |----xx_platform_cfg.h The xx_app.h file is included in this layout only because table handles are -typically stored in an application's AppData_t structure. +typically stored in an application's AppData_t structure. The file xx_tbldefs.h (sometimes just named xx_tbl.h) typically contains the structure definition of a single table entry. This file is included in the @@ -2798,7 +2795,7 @@ The xx_tbl.c file typically contains table-related utility functions. For instance, many applications define table initialization and validation functions in this file. -The xx_table1.c file is the source code for a table itself. +The xx_table1.c file is the source code for a table itself. The xx_platform_cfg.h file contains configuration parameters for applications, and there are typically several configuration parameters associated with tables. @@ -2896,7 +2893,7 @@ int32 XX_ValidateTable(void *TableData) { /* validate each entry of the table */ ... - } + } ... return Status; @@ -2939,7 +2936,7 @@ FILE: xx_platform_cfg.h #define XX_TABLE_ENTRY_COUNT 3 ``` -## 8.6 Building Tables +## 8.6 Building Tables In order to build application tables with the CMake build system, the "add_cfe_tables" command needs to be added to the CMakeLists.txt file. If the diff --git a/docs/src/cfe_api.dox b/docs/src/cfe_api.dox index cfeafb50b..b09273272 100644 --- a/docs/src/cfe_api.dox +++ b/docs/src/cfe_api.dox @@ -15,7 +15,6 @@
  • \ref CFEAPIESAppBehavior
  • \ref CFEAPIESChildTask
  • \ref CFEAPISBZeroCopy
  • \ref CFEAPISBSetMessage @@ -165,11 +163,6 @@
  • #CFE_MSG_GetTypeFromMsgId - \copybrief CFE_MSG_GetTypeFromMsgId
  • #CFE_SB_MessageStringGet - \copybrief CFE_SB_MessageStringGet -
  • \ref CFEAPISBChecksum -
  • \ref CFEAPISBMessageID