core Flight Executive (cFE) Open Source Release Readme
cFE Release 6.5.0
Date:
June 7, 2016
Introduction:
The Core Flight Executive is a portable, platform independent embedded system
framework originally developed by NASA Goddard Space Flight Center and now
maintained by the NASA wide community Configuration Control Board (CCB). This
framework is used as the basis for the flight software for satellite data
systems and instruments, but can be used on other embedded systems.
The Core Flight Executive is written in C and depends on another software
library called the Operating System Abstraction Layer (OSAL). The OSAL
is available at http://sourceforge.net/projects/osal/
and github.com/nasa/osal
This software is licensed under the NASA Open Source Agreement.
http://ti.arc.nasa.gov/opensource/nosa
The Core Flight Executive consists of the following subsystems:
- Executive Services - initializes and controls applications
- Software Bus - A publish and subscribe messaging system based
on CCSDS command and telemetry packets
- Time Services - Manages system time
- Event Services - Event reporting and logging services for applications
- Table Services - Data/parameter load and update services for applications
The Core Flight Executive is intended to host a suite of applications
and libraries. A small subset of the applications and libraries are included in
this distribution. A set of lab applications provide a means of scheduling the
cFS system, as well as, commanding and receiving telemetry. A sample library
and sample application are included to help verify that the build and runtime
are configured correctly.
Release Notes:
cFE Release 6.5.0 does NOT support the following system requirements:
cES1515.1 "If the creation of the operating system object fails, the cFE shall
perform a power on reset."
The cause of this requirement failure is due to a failure to call the
CFE_PSP_Restart function from the CFE_ES_CreateObjects function when the return
from OS_TaskCreate != OS_SUCCESS (cfe_es_start.c, line 865). Instead the
CFE_PSP_Panic function is being called (cfe_es_start.c, line 882). The
CFE_PSP_Panic function makes a call to exit(-1), resulting in termination of the
cFS system vs. a power on reset. This failure will be addressed in the next
release of the cFE. It should be noted that the current behavior is consistent
with previous releases of the cFE. There are two workarounds to this failure:
1. Replace the call to CFE_PSP_Panic (cfe_es_start.c, line 882) with a call
to CFE_PSP_Restart(CFE_PSP_RST_TYPE_POWERON).
2. Update the CFE_PSP_Panic function to perform the desired behavior.
cES1702.3 "If the CPU exception was caused by the Operating System or cFE Core
then the cFE shall initiate a <PLATFORM_DEFINED> response."
In the previous release of the cFE (version 6.4.2), this requirement was being
satisfied via the PSP making a call to the cFE platform defined exception
handling function. Changes to the PSP (PSP version 1.3.0) resulted in the
failure of this requirement. cFE requirements must be satisfied by the cFE.
This failure will be addressed in the next release of the cFE. To workaround
this failure:
Replace the call to CFE_ES_ProcessCoreException (cfe_psp_exception.c, line 155)
with:
CFE_ES_EXCEPTION_FUNCTION((uint32 )task_id,
(uint8 *)CFE_PSP_ExceptionReasonString,
(uint32 *)&CFE_PSP_ExceptionContext,
sizeof(CFE_PSP_ExceptionContext_t));
Note: The CFE_ES_EXCEPTION_FUNCTION prototype will need to be imported into
the cfe_psp_exception.c source file. Also, the cfe platform configuration
variable CFE_ES_EXCEPTION_FUNCTION defined in the cFE_platform_cfg.h file will
need to be updated to call the desired function.
cES1703.3 "If the Floating Point exception was caused by the OS or cFE Core then
the cFE shall initiate a <PLATFORM_DEFINED> response."
In the previous release of the cFE (version 6.4.2), this requirement was being
satisfied via the PSP making a call to the cFE platform defined exception
handling function. Changes to the PSP (PSP version 1.3.0) resulted in the
failure of this requirement. cFE requirements must be satisfied by the cFE.
This failure will be addressed in the next release of the cFE. To workaround
this failure:
Replace the call to CFE_ES_ProcessCoreException (cfe_psp_exception.c, line 155)
with:
CFE_ES_EXCEPTION_FUNCTION((uint32 )task_id,
(uint8 *)CFE_PSP_ExceptionReasonString,
(uint32 *)&CFE_PSP_ExceptionContext,
sizeof(CFE_PSP_ExceptionContext_t));
Note: The CFE_ES_EXCEPTION_FUNCTION prototype will need to be imported into
the cfe_psp_exception.c source file. Also, the cfe platform configuration
variable CFE_ES_EXCEPTION_FUNCTION defined in the cFE_platform_cfg.h file will
need to be updated to call the desired function.
There were some minor API changes to this build that may result in compiler
warnings with applications/tasks built via previous cFE releases. It is known
these API changes affect the Health and Safety (HS) application version 2.2.0
and the Stored Command (SC) application version 2.4.0. Minor updates are
needed to support compatability. These updates include:
1. In sc_cmds.c, line 911 needs to be updated to:
int32 TableID = (int32) ((CFE_TBL_NotifyCmd_t *) CmdPacket)->Payload.Parameter;
2. In hs_monitors.c, line 268 needs to be updated to:
(HS_AppData.EMTablePtr[TableIndex].EventID == EventPtr->Payload.PacketID.EventID))
3. In hs_monitors.c, line 270 needs to be updated to:
if ( strncmp(HS_AppData.EMTablePtr[TableIndex].AppName,
EventPtr->Payload.PacketID.AppName, OS_MAX_API_NAME) == 0 )
For detailed information on what is included/missing from this release, reference
the cFE 6.5.0 Version Description Document.
Software Included:
Core Flight Executive ( cFE ) 6.5.0
Platform Support Package (PSP) library
Classic core Flight System (cFS) Mission Build system
Cmake Mission Build system
Applications:
Sample Library -- an example of a CFS library
Sample App -- an example of a CFS application
CI_LAB -- A test application to send CCSDS Command packets to
the system over UDP/IP
TO_LAB -- A test application to subscribe to and send CCSDS
telemetry packets over UDP/IP
SCH_LAB -- A test application to schedule housekeeping
packet collection.
Simple Command and Telemetry utilities
The command and telemetry utilities provide a basic ground system
for desktop testing via UDP/IP connections to ci_lab and to_lab.
The utilities use python 2.x and the QT 4.x GUI libraries. The forms
were designed in the QT4 designer program. The python bindings used are the
PyQT4 bindings. On Ubuntu 12.04 LTS for example: use the following command
to install the software needed to run the utilities:
$ sudo apt-get install python-qt4 pyqt4-dev-tools
cmdUtil -- A simple command line utility to format and send CCSDS command
over UDP/IP to the CI_LAB application. Located in cfe/tools/cmdUtil.
Before using cmdGui, run "make" in this directory to build the
cmdUtil binary.
cmdGUI - A simple python/QT4 based utility that allows you to define and
send commands using the cmdUtil program.
cmdGui is started by running:
$ python ./CommandSystem.py
tlmUtil -- A simple python/QT4 based utility that allows you to define and
display telemetry received from the TO_LAB application.
tlmUtil is started by running:
$ python ./TelemetrySystem.py
Software Required:
Operating System Abstraction Layer 4.2.0 or higher
Can be obtained at http://sourceforge.net/projects/osal
or github.com/nasa/osal
Supported Build and Runtime Environment:
Build Environment Supported:
This software is configured to build "out of the box" on a pc-linux x86
( 32 bit ) environment.
It should be possible to build on recent linux distributions
( CentOS, RedHat, Debian, Ubuntu, SUSE, etc ). It should also build and run
as a 32 bit or 64 bit executable on a 64 bit system. See the Version
Description Document, Section 1.5, for a listing of tested platforms.
It should be possible to build on Windows and Mac OS X, but is not currently
tested/supported. The platform support packages (psp) for mac-osx and pc-cygwin
have been decommissioned. It is recommended to start with the pc-linux PSP
implementation for building on Windows and Mac OS X, updating the PSP
implementation as necessary for these PC operating systems.
Runtime Targets Supported:
The "out of the box" targets in this distribution include:
1. 32 bit x86 Linux
Other targets:
Other targets are included via the OSAL and PSP libraries, but may take
additional work to run.
Note: The cFE assumes use of the "char" data type as an 8-bit type.
Quick start:
The following assumes you are in a CentOS/RHEL terminal. The cFE distribution
file is in a directory called "Projects".
Unpack the cFE distribution
[cfe@localhost ~]$ cd Projects
[cfe@localhost Projects]$ tar -zxf cFE-6.5.0-OSS-release.tar.gz
[cfe@localhost Projects]$ cd cFE-6.5.0-OSS-release
Unpack the OSAL distribution ( obtain from sources above )
Assuming the file is in your Projects directory
( example: /home/acudmore/Projects/osal-4.2.0-release.tar.gz)
[cfe@localhost cFE-6.4.1-OSS-release]$ tar -zxf ../Projects/osal-4.2.0-release.tar.gz
[cfe@localhost cFE-6.4.1-OSS-release]$ mv osal-4.2.0-release osal
Build the cFE source code
NOTE: In the first command, make sure you enter a '.' then a space
then './setvars.sh' !!!
( see the bash command "source" )
[cfe@localhost cFE-6.4.1-OSS-release]$ . ./setvars.sh
[cfe@localhost cFE-6.4.1-OSS-release]$ cd build
[cfe@localhost build]$ cd cpu1
( Note: cpu1 is configured for the pc-linux target )
[cfe@localhost pc-linux]$ make config
( Note: this copies all of the needed configuration make and header files )
[cfe@localhost pc-linux]$ make
( Note: this builds the OSAL, cFE, and apps )
When the build completes, the cFE core executable that runs on on CentOS is
in the exe directory. It can be run by doing the following:
[cfe@localhost cpu1]$ cd exe
[cfe@localhost exe]$ ./core-linux.bin
At this point, the linux version of the cFE will start running. Note that the
OSAL uses POSIX message queues to implement the inter-task communication
queues.
The cFE by default needs a larger "msg_max" parameter in linux to run. There
are two solutions to this problem:
1. increase the /proc/sys/fs/mqueue/msg_max parameter
2. run the cFE core as root
[cfe@localhost exe]$ su
( type in root password )
[cfe@localhost exe]# ./core-linux.bin
Root/sudo is also required to enable the linux real time scheduler for
more accurate priorty control.
With the cFE starting, it should initialize, then read the cFE startup
script and load the library and applications.
New applications can be added by editing the cfe_es_startup.scr file.
Stop the cFE and all applications by hitting control-c in the terminal
When the cFE and CFS applications are running, you can start the
CommandSystem.py and TelemetrySystem.py and try some simple commanding.
Where to find more info:
There is much more information that is beyond the scope of a readme file.
The current documents can be found in the following directories:
cFE-6.5.0-OSS-release/docs
cFE-6.5.0-OSS-release/osal/docs ( once the OSAL is installed )
cFE-6.5.0-OSS-release/cfe/docs
cFE-6.5.0-OSS-release/cfe/docs/doxygen/index.html -- a good place to start
for the cFE
