cFS Tutorial Stage 2: Transform the NASA sample_app To Your Own ...

Copy & Customize Stock cFS sample_app and Connect It Up Build Automation ...

by David Ferreira

NOTE: This post is a sequel to my first cFS tutorial. These steps assume you have completed all the steps in the prior post. Without those step, these instructions will make no sense.

Intro

In my last post, we downloaded NASA's cFS framework, made a slight modification to the NASA sample_app and then build it and ran it.

In this post, we will start where we left off and progress to cloning the sample_app and making it our own. We will focus on the idiosyncrasies of loading a new application module on cFE boot and linking our new, cloned application into the existing cFS build automation which relies on CMake and make to build both the applications and the framework. This is very much non-trivial and worthy of its own blog post.

This post WILL NOT FOCUS ON how to efficiently rename 20+ files at a time in Linux terminal. Nor will we focus clever use of find/replace in a text editor to bulk rename variables in a .c or .h file. You may follow along with my video on how I accomplish these mundane tasks, but those steps will not be here in this post, neither do I represent my steps as being the most efficient.

Steps:

1. Install VSCode

Boot the Linux or Pi OS virtual machine you created in the last tutorial. Login and open up the terminal. Run these commands:

sudo snap install --classic code

sudo apt install rename 

2. Review step:  Let's add a line of code to identify the sample_app

a. Open VSCode (installed in Step 1) and open the folder ~/src/cFS

VSCode will conveniently treat this as a project and organize the files for you in it's Explorer pane.

b. In VSCode Explore pane, browse for and open the file

cFS/apps/sample_app/fsw/src/sample_app.c

c. In this file, search for the expression "RunLoop" (this should take you to line 69, approx.)

d. Now within this "RunLoop" look for the if statement with the clause "status == CFE_SUCCESS". Let's place the following printf statement just before the closing brace of this block of code ... around line 87:

printf("<<<<< Sample App: Go Artemis! >>>>>\n");

This will make it more obvious that our sample_app is actually running when we execute the cFE.

Don't forget to save this file now. ;) 

3. Now let's do a sanity check by building & running before we make more major changes.

a. Back at our Terminal prompt, let's start in our cFS directory and build and run:

If, after waiting for initialization plus a few seconds (say, 10 seconds total), you don't see our message printing out, they you may have done something wrong. I would suggest returning to Step 2 and retrying them.

If you see our message being printed out every few seconds, then we're good to proceed.

If NOT, I would suggest reviewing my prior video & blog post to make sure you followed setup instructions properly.

4. Copy entire sample_app directory with a recursive copy command:

5. Rename all the sample_app source files

Let's replace the expression "sample_app" with "my_app" in all the filenames in this folder.

6. Fix filename references in the code that were broken by bulk filename changes

The code for sample_app contained references to the files we renamed in step 3. The project can't possibly build properly until we fix those references.

Additionally, you'll want to replace the output sub-string "<<<<< Sample App: " to "<<<<< My App:". And you may want to replace "sample" in variable names and macros, although many of these cases have little concrete importance.

This will be an iterative process and will rely on some basic familiarity C/C++ programming rules and interpreting compile errors. It's not practical for me to enumerate every case where code needs to be changed or where a change SHOULD NOT be made. I must defer to your best judgement and debugging skills. 

Having said that, here are a some starting points to speed up your change process.

a. Run VSCode and in VSCode open the cFS folder (~/src/cFS).

b. Browse for the folder apps/my_app/fsw/src and open the file my_app.c

c. In this file use the edit pane to search and replace. 

c. Do the same in all the other files in this directory.

d. Consider renaming the included header files that reside under the my_app directory. This will bring them in line with the #include statements in the code that you probably already changed.

7. <<IMPORTANT>> This step is the "meat and potatoes" of our tutorial: Make changes to sample_defs files so your new my_app gets built and loads at runtime.

a. In VSCode, navigate to the cFS/sample_defs folder and look for the file called targets.cmake. Edit this file to add my_app to the build instructions. See figure below for help.

 b. Also in VSCode navigate to the file cFS/sample_defs/cpu1_cfe_es_startup.scr. Create a new entry in this table by duplicating the line for sample_app (line #3) and creating a new line for my_app. Make sure your edits correspond to the code changes (search & replace?) that you did in step 6c. You only need to alter fields 2, 3, and 4 of the new row.

(See figure below for helpful hints.)

8. Let's go back to your terminal (home directory), rebuild and re-run

 

cd                                   
make SIMULATION=native prep          
make                                 
make install                         
cd build/exe/cpu1/                   
./core-cpu1                          

 

Carefully examine any compiler or build errors that may occur. If there are many, scroll up and examine the first error first. What file and line did it occur in? etc.

9. Expected results

 

If you’re done everything correctly, we expect you’ll see a few screens of initialization output where you will see your sample app's name mentioned.

After initialization, you should expect to see any print statements that you added.

If it didn’t work out quite as expected, don’t lose heart. Use common sense to retrace the steps that went wrong.