nasa/osal

The Core Flight System (cFS) Operating System Abstraction Layer (OSAL)

Core Flight System : Framework : Operating System Abstraction Layer

This repository contains NASA's Operating System Abstraction Layer (OSAL), which is a framework component of the Core Flight System.

This is a collection of abstraction APIs and associated framework to be located in the osal subdirectory of a cFS Mission Tree. The Core Flight System is bundled at https://github.com/nasa/cFS, which includes build and execution instructions.

The autogenerated OSAL user's guide can be viewed at https://github.com/nasa/cFS/blob/gh-pages/OSAL_Users_Guide.pdf.

Quick Start:

Typically OSAL is built and tested as part of cFS as detailed in: cFS repo

OSAL library build pc-linux example (from the base osal directory):

mkdir build_osal
cd build_osal
cmake -DOSAL_SYSTEM_BSPTYPE=generic-linux ..
make

OSAL permissive build with tests example (see also CI)

mkdir build_osal_test
cd build_osal_test
cmake -DENABLE_UNIT_TESTS=true -DOSAL_SYSTEM_BSPTYPE=generic-linux -DOSAL_CONFIG_DEBUG_PERMISSIVE_MODE=TRUE ..
make
make test

See the Configuration Guide for more information.

See also the autogenerated user's guide: https://github.com/nasa/cFS/blob/gh-pages/OSAL_Users_Guide.pdf

Known issues

See all open issues and closed to milestones later than this version.

Getting Help

For best results, submit issues:questions or issues:help wanted requests at https://github.com/nasa/cFS.

Official cFS page: http://cfs.gsfc.nasa.gov

osal's Issues

Fix warnings in OSAL "unit-test" code

The code in the "unit-tests" directory in OSAL has a number of warnings when it compiles and this is one thing preventing turning on the strictest compiler settings (-Wall -Werror, etc) during the build.

Many of the warnings are related to passing a non-const string directly to a printf function when logging test results.

Many compiler warnings in unit tests when using strict compiler flags

Describe the bug
For historical backward-compatibility reasons ANSI C defines string literals as char* type, but these strings are typically put into an .rodata section on modern processors/linkers, and this section is usually write-protected. If code actually attempts to modify this value, it will generate a segmentation fault and crash.

Building with -Wwrite-strings causes the compiler to treat string literals as const char * instead, thereby generating a warning if passed or assigned to a non-const pointer value.

To Reproduce
Configure with make OSAL_USER_C_FLAGS='-Wall -Werror -std=c99 -pedantic -Wwrite-strings' ENABLE_UNIT_TESTS=true and observe many warnings generated in the unit test code.

Expected behavior
The build should be free of warnings, such that -Wwrite-strings can be enabled by default.

System observed on:
Ubuntu 18.04 (64-bit)

Reporter Info
Joseph Hickey, Vantage Systems, Inc.

Binary Semaphore Can not be set 0 when it create

osal/src/os/posix/osapi.c

Line 2274 in 75beb86

if ( sem_initial_value > 1 )

I think this statement has a problem.

If I input semaphore with initial value 0, this statement ignores input value 0 and make it 1

Is there any other intention that I missed?

if not I recommend to fix statement
if (sem_initial_value < 0) >>> if (sem_initial_value <= 0)

Write XML files for Bamboo

We use the Atlassian ''Bamboo'' system to automatically build
the project, run the test, and present the results, but the
system is not an oracle: it requires test results to be in
one of the several forms for which it has parsers.

I was able to construct XML files that Bamboo's "JUnit Results"
parser was able to handle. This commit introduces a simple
implementation of a file writer for those files.

This is a ''bare-bones'' implementation, onto which we can
hang future enhancements. Note that there are rules for
quoting data in strings, and text not within <..> tags;
the simple approach taken here is merely to completely avoid
the use of any character that needs quoting.

My intention is to continue work on this when I get back
from vacation on the 23rd.

Refactor common code between VxWorks/Posix/Rtems into OSAL shared layer

The OSAL library is essentially three separate libraries sharing a common API. The VxWorks, Rtems, and Posix implementations do not share any code aside from the common osapi header files. Depending on the OS selection, one of the three libraries will be compiled.

However, under the hood, many of the operations within these three libraries are very similar. Although the final call down into the OS differs, much of the "housekeeping" that OSAL performs is similar between all three implementations.

Each of them maintain internal tables that map OS objects to names and numbers, and all the OSAL API calls check their arguments against these internal tables to see e.g. if an object by some ID is valid or if an object by some name already exists.

All this housekeeping //really should be identical// and it could be argued that any difference is really a bug and not a feature, as differences here could affect the portability of application code from one OS to another.

Refactoring this "common" functionality into a layer which is actually shared among OS implementations provides several benefits:

• Cuts down on the code in the actual OS-specific portions by about 50%, and the code that is left is much more direct and "to-the-point". For instance, an implementation of creating a semaphore //ONLY// needs to create the actual semaphore and return a success/fail code. All locking, table manipulation, error checking, and recovery is handled by the shared/common layer.
• This makes additional operating system layers easier to implement and less costly to maintain in the future.
• Likewise, abstraction of additional OS features (such as network sockets) is easier to implement and less costly to maintain in the future.
• Ensures that the housekeeping operations are done consistently across ALL supported operating systems. This greatly reduces the chances of operations working differently on one OS vs another. This is particularly true of error conditions that may not be exactly the same or recovered in the same way between current OS implementations.

OSAL public/private data structure delineation

This ticket was originally part of ticket #36 but the change was independent and significant enough to warrant breaking this out into a separate review item.

This will fix some issues with the OS Module API:

• CPU addresses must be stored using the "cpuaddr" type, not uint32.

• The "OS_module_record_t" should be made into an OS-dependent structure, as the different OS layers may have different sets of data that they need to retain for loaded modules. This will also make it more consistent with the other APIs -- e.g. Tasks, Queues, Semaphores all define their internal record structures in the OS-specific implementation and not part of the public API.

• The OS_ModuleInfo() call should return a standardized structure and not the direct internal record. This will also be more consistent with the way the other APIs do this where they have a separate "prop" structure that is returned that is defined as part of the public API.

OSAL "common_types.h" is not completely reliable

On some systems (particularly 64-bit) the types defined in OSAL "common_types.h" file do not always match their expected widths.

There is currently a very helpful compile-time assert to catch this if it does go wrong but we need it to not go wrong in the first place.

The best way to solve this is to leverage the C "stdint.h" file - this has been standard since C99. For any C library that does not have this header it can fall back to using the existing defines.

Duplicate OSAL error codes and error string API

osapi-os-filesys.h has its own set of error codes that overlap with and are different from the rest of OSAL error codes. For example, "OS_FS_ERR_NAME_TOO_LONG" is not the same as "OS_ERR_NAME_TOO_LONG". There are several codes that are redefined differently. At a minimum, this is confusing, but it can also cause real bugs if the wrong action is taken due to misinterpreting an error.

Furthermore, FS has a second implementation of OS_GetErrorName called OS_FS_GetErrorName() that only translates the FS error codes. Passing an error code from one of the filesystem functions into OS_GetErrorName will get the wrong string.

This should be cleaned up - the FS error codes should be merged with the rest of OSAL error codes into a single set, with a single implementation of OS_GetErrorName() to get them all.

Document available OSs in trac wiki

It would be helpful to construct a small Wiki page corresponding
to each Operating System implementation giving a quick overview of
the platform for which support is being provided.

I suggest including hotlinks on each such page back into the doc
subtree of the specific OS for extended documentation -- as clones
will obtain the content of the project sources but do not clone
the Trac wiki.

Rtems timer can not be disabled

I think Rtems OS_timerset() not satisfy it's description in API document

osal/src/os/rtems/ostimer.c

Line 368 in 75beb86

if ( start_time > 0 )

In POSIX API, Call OS_timerSet() with "start_msec = 0" causes timer stop but Rtems just ignore that parameter

I hope to change OSAL rtems api code to

if ( start_time > 0 ) {
OS_UsecsToTicks(start_time, &timeout);
status = rtems_timer_fire_after(OS_timer_table[timer_id].host_timerid,
timeout,
OS_TimerSignalHandler, (void *)timer_id );
if ( status != RTEMS_SUCCESSFUL )
{
return ( OS_TIMER_ERR_INTERNAL);
}
} else {
status = rtems_timer_cancel(OS_timer_table[timer_id].host_timerid);
if ( status != RTEMS_SUCCESSFUL )
{
return ( OS_TIMER_ERR_INTERNAL);
}
}

qnx osal

Does such exists in nature?

add locking during test runs

The build support scripts presume they have unique ownership
of the test target. This assumption may be violated if the
script is run manually.

This can be resolved by using the flock(1) command to set up
an advisory lock within the shell script.

Document stand-alone build using cmake

Is your feature request related to a problem? Please describe.
Unable to replicate old make functionality with cmake in a stand-alone OSAL repo

Describe the solution you'd like
Document how to build, execute coverage tests, execute functional tests, and report coverage using cmake (or if the capability doesn't exist, add it).

Describe alternatives you've considered
Update build/*

Additional context
N/A

Requester Info
Jacob Hageman/NASA-GSFC

Add Xenomai OSAL

Add Xenomai OSAL V1.0 as delivered from Matt Benson/Odyssey Space Research on 04/17/15

API prototype changes to address compiler warnings

These areas of the OSAL API need clean up.

Task API:

• OS_TaskCreate() stack pointer is declared const (read-only). By definition, stack space should not be read-only.
• OS_TaskInstallDeleteHandler() takes a "void *" argument rather than a function pointer. This should be a function pointer.

Module API:

• To be consistent with the other API's, a separate property structure should be defined for use with OS_ModuleInfo(). Currently this returns the internal OSAL "OS_module_record_t", while all other API's return a dedicated property object. This is necessary to allow the internal implementation of the OSAL to change in the future while preserving the public API types.
• The types should be changed to use the "cpuaddr" type rather than uint32 where a memory address is stored (OS_module_address_t, OS_SymbolLookup())

General:

• When passing character strings as input to functions these should preferably be declared as "const char *" whenever possible. This allows one to pass string literals into the function. Otherwise a warning may be generated if a literal is used for a parameter declared as "char *".

Microsecond round up code doesn't round up.

Describe the bug
Spawned from #1

The code comment claims it rounds up to never return zero. The formula implemented doesn’t actually round up in all cases, since generally when casting a float/double to an int you lose the fractional part (truncation, not rounding). So the code is not self-consistent. It’s not a POSIX or OS issue, it’s that the code doesn’t do what it says it does. The API document doesn’t specify a non-zero guarantee.

osal/src/os/posix/ostimer.c

Lines 284 to 290 in bfa7a33

	/*
	* Calculate microseconds per tick - Rounding UP
	* - If the ratio is not an integer, this will choose the next higher value
	* - The result is guaranteed not to be zero.
	*/
	OS_SharedGlobalVars.MicroSecPerTick = (1000000 + (OS_SharedGlobalVars.TicksPerSecond / 2)) /
	OS_SharedGlobalVars.TicksPerSecond;

Similar misleading comment at:

osal/src/os/posix/ostimer.c

Lines 231 to 232 in bfa7a33

	/* Round to the nearest microsecond */
	POSIX_GlobalVars.ClockAccuracyNsec = (uint32)(clock_resolution.tv_nsec);

For what it’s worth, on Linux (our Ubuntu dev system) this code reports 100 ticks per second, and 10000 usec per tick. But if you pass in high values for ticks per second, it does return zero when it claims to round up (try 2000000 ticks per second).

To Reproduce
Steps to reproduce the behavior:

1. Compile

#include <stdio.h>
void main()
{
  float num = 0.7;
  printf("float = %f, cast = %d\n", num, (int)num);
}

2. Execute:

float = 0.700000, cast = 0

Expected behavior
Expected code to match comment, round up to not equal zero. Algorithm doesn't work as claimed in comment.

System observed on:

• cFS development server
• OS: 4.4.0-146-generic #172-Ubuntu
• Versions: n/a, sample code shows behavior (although I poked in cFE to cause the same thing)

Additional context
Add any other context about the problem here.

Reporter Info
Jacob Hageman/NASA-GSFC

Fix OSAL build when using RTEMS "pc686" BSP

In the RTEMS distribution, the rtems_interrupt_catch() function is not always defined. It depends on the BSP build-time options, specifically if the macro "CPU_SIMPLE_VECTORED_INTERRUPTS" is defined set to FALSE then the API call is not available.

This causes a link error when building with the "pc686" BSP since OS_IntAttachHandler() calls rtems_interrupt_catch().

This ticket will simply add a preprocessor check for the above condition, and if rtems_interrupt_catch() is not available then OS_IntAttachHandler() should return OS_ERR_NOT_IMPLEMENTED.

Inline documentation on OSAL routines is incorrect/outdated in many places

Describe the bug
The comments in the function headers of many of the OSAL calls have become outdated and incorrect.

To Reproduce
N/A. This reflects source code comments only. Most evident on the "implementation" files which copied the comment block from the external function call.

Expected behavior
Comment blocks should better reflect reality of what the code does. The "real" comment block that describes the function should reside with the function prototype. The definition should also have a comment block but primarily for visual differentiation in the source code. This block should not re-describe the function, as this results in multiple copies of the same description and thus could become stale/divergent again.

Reporter Info
Joseph Hickey, Vantage Systems, Inc.

add osprintf to OSAL

JSC has developed a known and understood version of printf that has been code reviewed and unit tested. It can be used on platforms that do not provide a printf (such as ARCIN653) or as a known, trusted implementation of the printf function on other OSs. Currently, versions (there are small variations in the implementation between OSs) for the posix, VxWorks6, and ARINC653 OSALs are available.

Need to add branch with OSAL/src/os/posix, vxworks6, ARCIN653/osprintf.c and OSAL/src/os/inc/psprintf_priv.h, osprintf.h

Add OSAL abstraction for network/socket interface

Currently the OSAL has a very minimal abstraction for network/socket functions.

Network operations are a common requirement and the presence/type of network stack can vary, such as BSD-style sockets or the lightweight IP (LwIP) stack. This is a prime candidate for addition to the OSAL. The abstraction layer should contain:

• Abstraction of OS socket address (sockaddr_in/_in6 for IPv4 and IPv6 at least)
• Abstraction of Stream/TCP & Datagram/UDP socket creation
• Bind/Listen for TCP
• Sendto/Recvfrom for UDP
• Abstractions for the basic inet_aton()/inet_ntop() IP-address

update OSAL for Class A & Associated unit tests

The currently released OSAL unit tests may not fully run with OSAL 4.1.1.

JSC has made updates so that they run with Linux and ARINC653 OSAL 4.1.1.

JSC is currently updating to work with VxWorks 6.7.

These updates are being tracked in the JSC subversion repo and need to be pushed into a proper git branch and further work continued from there.

API versioning for OSAL

The OSAL version ID e.g. "4.1.0.0" can also be used by application code to determine API features in case they change over time.

Although the existing OSAL API is intended to remain stable across versions, new calls can (and should) be added when appropriate. However this presents a problem for backward compatibility as new code written against a new API cannot be compiled with an older version of OSAL.

This is a common problem and is generally solvable by creating/checking a version macro. For example, glibc uses "POSIX_C_SOURCE" as an integer to define which version of POSIX it should behave like.

The OSAL should do the same, and create an "OSAL_API_VERSION" macro that application code can check to see what version of the API the current OSAL supports. Application code can then adjust itself accordingly, either by compiling without the new feature or generate a compile error if that feature is required.

Test `bin-sem-flush-test` does not compile

OSAL fails to compile with a clean clone of the repo.

(.venv) chris@linux-fkyc:~/Workspace/osal> source setvars.sh 
(.venv) chris@linux-fkyc:~/Workspace/osal> cd build/
(.venv) chris@linux-fkyc:~/Workspace/osal/build> make config
test -d inc || mkdir inc
cp -f ../src/bsp/pc-linux/config/osconfig.h inc/osconfig.h
(.venv) chris@linux-fkyc:~/Workspace/osal/build> make
make -C tests 
make[1]: Entering directory '/home/chris/Workspace/osal/build/tests'
make -C bin-sem-flush-test 
make[2]: Entering directory '/home/chris/Workspace/osal/build/tests/bin-sem-flush-test'
gcc  -I/home/chris/Workspace/osal/src/inc -I/home/chris/Workspace/osal/src/os/inc -I/home/chris/Workspace/osal/src/tests/bin-sem-flush-test -I/home/chris/Workspace/osal/src/../ut_assert/inc -I../../inc   -D_EL -DENDIAN=_EL -DSOFTWARE_LITTLE_BIT_ORDER  -D__ix86__ -D_ix86_ -D_LINUX_OS_ -Dposix -DX86PC -DBUILD= -D_REENTRANT -D _EMBED_  -D_XOPEN_SOURCE=600   -Wall -pedantic -std=c99 -Wstrict-prototypes -O1 -DOS_DEBUG_LEVEL=3 -c -o bin-sem-flush-test.o /home/chris/Workspace/osal/src/tests/bin-sem-flush-test/bin-sem-flush-test.c
In file included from /home/chris/Workspace/osal/src/tests/bin-sem-flush-test/bin-sem-flush-test.c:5:0:
/home/chris/Workspace/osal/src/os/inc/common_types.h:326:38: error: size of array ‘TypeUint32WrongSize’ is negative
 CompileTimeAssert(sizeof(uint32)==4, TypeUint32WrongSize);
                                      ^
/home/chris/Workspace/osal/src/os/inc/common_types.h:104:60: note: in definition of macro ‘CompileTimeAssert’
 #define CompileTimeAssert(Condition, Message) typedef char Message[(Condition) ? 1 : -1]
                                                            ^
/home/chris/Workspace/osal/src/os/inc/common_types.h:330:38: error: size of array ‘Typeint32WrongSize’ is negative
 CompileTimeAssert(sizeof(int32)==4,  Typeint32WrongSize);
                                      ^
/home/chris/Workspace/osal/src/os/inc/common_types.h:104:60: note: in definition of macro ‘CompileTimeAssert’
 #define CompileTimeAssert(Condition, Message) typedef char Message[(Condition) ? 1 : -1]
                                                            ^
/home/chris/Workspace/osal/src/make/app-rules.mak:21: recipe for target 'bin-sem-flush-test.o' failed
make[2]: *** [bin-sem-flush-test.o] Error 1
make[2]: Leaving directory '/home/chris/Workspace/osal/build/tests/bin-sem-flush-test'
Makefile:2: recipe for target 'all' failed
make[1]: *** [all] Error 2
make[1]: Leaving directory '/home/chris/Workspace/osal/build/tests'
Makefile:8: recipe for target 'all' failed
make: *** [all] Error 2
(.venv) chris@linux-fkyc:~/Workspace/osal/build> 

Clean up "-D" compile time macros used in pc-linux build

This is the equivalent of trac 17 in the CFE PSP -- see [https://babelfish.arc.nasa.gov/trac/cfs_psp/ticket/17]. The same build flags are duplicated in the OSAL BSP.

The "pc-linux" OSAL BSP defines the following to be added to the compiler CFLAGS:

{{{-D_EL -DENDIAN=EL -DSOFTWARE_LITTLE_BIT_ORDER -D__ix86_ -D_ix86_ -Dposix -DX86PC -D_REENTRANT -D_EMBED_ -DOS_DEBUG_LEVEL=3}}}

These were brought into the cmake build from the original build scripts in order to be consistent just in case any code required it. However, they are unnecessary, many are not even used anywhere in CFE/OSAL, and potentially even wrong.

The reality is that with Linux, the "pc-linux" is a general purpose PSP that can most likely be used on any general-purpose development machine that runs Linux. It is not limited to only x86 PC's, and in fact works just fine on ARM, PowerPC, and Microblaze targets too.

I have successfully used the (unmodified) pc-linux BSP to execute unit tests on a BeagleBone Black (ARM) as well as an emulated PowerPC 440 based development machine. In all these cases, the "x86" macros are wrong, and on the PowerPC, the EL/ENDIAN/SOFTWARE_LITTLE_BIT_ORDER are wrong too.

To summarize - I recommend removing ALL of these macros from the pc- linux build when using the cmake scripts (the old makefiles can stay as- is).

Bogus usage of strncpy in unit tests

There are several places in OSAL where the Buffer Overflow protection
feature of the strncpy() function is used incorrectly, in a way that causes
it to not protect against buffer overflow.

Correct usage is to pass the size of the destination area as
the third argument, so strncpy() will stop before trying to write
past the end of the destination storage.

Incorrect usage observed is passing the length of the SOURCE string
as the limiting size. The resulting behavior is:

• Call strlen() to get length of source data.
• Call strncpy() to copy the string
• strncpy() copies bytes until it sees NUL or copies N bytes.
• in this case, it will always copy all data, and stop before the NUL.

The upshot of this is strncpy() always copies the whole source
string and never writes a terminating NUL.

Better usage would be to present the destination buffer size
as the limiting size in the 3rd argument (yes, strncpy() stops
writing after writing the NUL).

Update OS_TimerSet API documentation for timer disable

Is your feature request related to a problem? Please describe.
As stated in #9, the OS_TimerSet documentation does not match behavior.

Describe the solution you'd like
API documentation should describe OS_TimerDelete() as the method to cancel the timer (not a start time of zero)

Describe alternatives you've considered
None

Additional context
None

Requester Info
Jacob Hageman/NASA-GSFC

TSF: osloader OS_ModuleLoad #4

The OS_ModuleLoad test case in the osloader unit test fails
during the "test setup" loop. Once the test was augmented to
report the failing module name, it was discovered that this
was due to not staging the "MODULE%d.so" files to the target
running the unit tests.

Repairs actually applied to the build script over in
the cfs_test project (cfs_test/osal/build.sh).

OSAL PPC VxWorks "test runner"

Independent of any other issues with building test code for
the PowerPC running VxWorks -- it appears that I will need
a small bit of "helper code" in order to make my testing
environment a little bit more robust.

Currently, running a unit test requires someone, by hand,
to do the following steps for each test:

• Observe the value of (int)OS_BSPMain
• issue ld < testname.elf command
• Watch out for any ''undefined symbol'' errors
• Verify that (int)OS_BSPMain changed
• issue sp(OS_BSPMain) command
• Monitor console output watching for the test to finish
• perhaps reboot the target if things went horribly wrong

Running the tests by calling OS_BSPMain() directly from
the shell introduces problems if the test program makes any
changes in the task that disturb the shell -- most notably,
if the task calls exit() all bets are off.

What I want in a "test runner" is to have code that supervises
loading of the program, detects any load errors, and assures that
the loaded image provides a suitable entry point. If all is
good, start the test as a subtask. The runner needs to then
wait for the task to complete, which unfortunately requires
it to periodically test to see if the task is still alive.

A nice thing to have for this sort of facility is a timeout,
which turns out to be pretty trivial given that we have to
drop into a polling loop. If we loop too long, we can kill
off the task and make appropriate log annotations.

The initial runner I envision is simply an image to be
loaded after the target boots, exporting a function that
does the work for one test, coupled with a script that
loads the image and calls the function for each test
to be run.

Alternate time references for OSAL timers

OSAL currently has a timer API which references only to the real time clock in the CPU. All timers created using the OS_TimerCreate() / OS_TimerSet() API are always based on the same clock reference.

However, in an embedded system, a local clock may not always be the real reference for events; many systems derive their timing from an external entity which is NOT necessarily synchronized to the local CPU clock.

This ticket will add a new type of OSAL object called a "Time Base". By default a time base can be driven from the local CPU real time clock, which will mimic the current behavior of timers. However the BSP/PSP may create additional time bases and synchronize them to e.g. an external timing interrupt. The same existing "TimerSet" API can be used to set the timers against the alternate time base and it will be transparent to the app.

2015-02-12 Integration Candidate

This ticket will collect branches to be merged and tested based on the 2015-02-02 CCB.
Further details will be added in comments.

Implement user-selectable compiler warning switches

It has become apparent that a "one-size-fits-all" approach to compiler warnings may not be sufficient going forward.

In general, most developers should be using "-Werror" in addition to "-Wall", "-pendantic", etc to catch any coding issues at first sight.

However, the specific set of warnings for any given piece of code is dependent on the specific compiler version, target architectures, and optimization level in use at the time of build. This can mean code that builds without warnings on one build can fail miserably on a different build.

This could be an major issue for a novice who clones the latest code from the community repository, and builds it with the latest version of GCC (i.e. one that we may not have tested yet) and finds a new warning that causes the entire build to fail unexpectedly.

As a compromise, the following is proposed:

• Always use "-Wall" switch to enable the most reasonable warnings (incidentally, this is not all warnings, it leaves out the ones most likely to generate false positives).
• Do not put "-Werror" in the official build scripts, so if compiling with a new GCC version or a different target architecture than the what has been officially tested, the build will not fail if a new warning is triggered.
• Also leave out "-pedantic" from the official build as this, by definition, tends to warn on constructs that are generally OK in practice but violate some (possibly esoteric) aspect of the C standard. The thought behind this is that plenty of old existing code out there may work fine but might not compile cleanly using "-pedantic", so we should not force this switch upon users by default.
• Add a mechanism by which developers can easily add extra CFLAGS to a build, without modifying a Makefile (or CMakeLists) file. This way, any users that want to may enable "-Werror" or "-pedantic" on their own builds, all the time, without having to maintain a private branch of the build script.

The automatic builds done by Bamboo, these will be built without "-Werror" but the build log will be checked for warnings, and the presence of any new warnings will be logged as a unit test error so they can be fixed before moving the code forward.

Document available BSPs in trac wiki

It would be helpful to construct a small Wiki page corresponding
to each Board Support Package giving a quick overview of
the platform for which support is being provided.

I suggest including hotlinks on each such page back into the doc
subtree of the specific BSP for extended documentation -- as clones
will obtain the content of the project sources but do not clone
the Trac wiki.

OSAL headers define a shared memory API that is not actually implemented anywhere

Describe the bug
The osapi-os-core.h header defines several prototypes e.g. OS_ShMemCreate(). However, these functions are not implemented anywhere, and are not used by CFE nor CFS apps.

To Reproduce
N/A - this is unused code.

Expected behavior
The headers should not include these prototypes if they are not implemented and there is no plan or requirement to implement them.

Code snips

/*
** Shared memory API 
*/
int32 OS_ShMemInit          (void);
int32 OS_ShMemCreate        (uint32 *Id, uint32 NBytes, const char* SegName);
int32 OS_ShMemSemTake       (uint32 Id);
int32 OS_ShMemSemGive       (uint32 Id);
int32 OS_ShMemAttach        (cpuaddr * Address, uint32 Id);
int32 OS_ShMemGetIdByName   (uint32 *ShMemId, const char *SegName );

System observed on:
Ubuntu 18.04 (64-bit)

Reporter Info
Joseph Hickey, Vantage Systems, Inc.

OS_PEND and OS_CHECK are backwards

For functions that have a "timeout" parameter, two special values are defined: "OS_PEND" can be used to wait forever, and "OS_CHECK" can be used to not wait at all / return immediately.

The issue is that "OS_PEND" is defined as "0" and "OS_CHECK" is defined as "-1". These should be the other way around.

The problem is not so much when the special values are used but rather when they are NOT used and the timeout is computed by subtracting a current time from a deadline time. If the result of that computation happens to be zero, the OSAL will interpret this as "OS_PEND" and will end up waiting forever.

Simply swapping the definitions of OS_CHECK and OS_PEND would make the operation much more logical by making a computed timeout of zero get the behavior of OS_CHECK and not OS_PEND.

OSAL should use UT framework similar to that of CFE

With trac ticket #29 (and related #30) now implemented, the OSAL tests can be used as one piece of a build verification tool suite.

However, the implementation is currently very basic - it does not use any real testing framework, it simply counts errors using a global integer added to each test.

CFE has a more sophisticated UT framework consisting of the following functions:

• UT_Text() - informational / log file text printing function;
• UT_Report() - provides a common method to check for a condition, along with code to log PASSED/FAILED in a consistent manner;
• UT_SetRtnCode() - ability to tailor the response code of stub functions in order to exercise error paths;
• UT_ReportFailures() - test summary generator

OSAL could benefit from using the same framework to run its tests. Most importantly, using the common "UT_Report()" API ensures that any errors that occur will be counted and logged in a consistent way. This is particularly important for automated tests, as a simple "grep" command can reliably find failures within log files containing thousands of test cases.

Add pc-rtems BSP to OSAL

For development under RTEMS it is helpful to have a basic BSP that does not require any special development boards.

The RTEMS project provides this via the "pc686" BSP. This makes it possible to boot and run an RTEMS application on ordinary commodity PC hardware.

This also boots and runs in virtual machines i.e. QEMU which is very desirable for testing.

This ticket will add a "pc-rtems" BSP to OSAL that can be used for this purpose.

Return OS_ERROR if OS_TimerSet is called with both parameters as zero

Is your feature request related to a problem? Please describe.
Related to the discussion in #9

Describe the solution you'd like
See title, as described in #9 (comment)

Describe alternatives you've considered
See #9 comment thread

Additional context
None

Requester Info
Jacob Hageman/NASA-GSFC

Make file system API work more like the rest of OSAL

In addition to the error code issue in ticket #34, other aspects of the filesystem API should be fixed to better integrate with the rest of OSAL:

• The filesystem API is not a full abstraction, it is only a light wrapper around the POSIX/C library functions. Similarly, the "os_fstat_t", "os_dirp_t", and "os_dirent_t" are directly typedef'ed to the C library types and not abstracted in any way. The effect of this is that any application code written using the OSAL filesystem API is ultimately still dependent on the underlying system libraries and headers, and the particular POSIX/C standard variant it supported, and may not be portable to other OS's.
• Due to the direct use of OS-supplied types and implementation, this implicitly adds a limitation that any OSAL filesystem must also map to a "real" filesystem recognized by the underlying OS. It is not possible to access a file storage device unless the OS already recognizes its filesystem.
• The API calls are defined differently and look/feel more like C library functions than the rest of OSAL. Some FS functions return an "int32" which serves as both an object ID and error code. Other FS function return a pointer and these have no way of returning a more descriptive error other beyond a NULL pointer. In the rest of OSAL, API functions pass back an object ID separately from the error code via a separate "uint32" parameter. This eliminates confusion of how to differentiate an error code from a valid object ID.

This can be fixed without breaking API compatibility with existing code:

• The types which are currently directly typedef'ed to the C library types can be properly abstracted. This will be transparent to application code as long as the names are preserved.
• A new file API can be introduced that works more like the rest of OSAL, and wrappers implemented to mimic the current API so that existing code still works. To save code memory space, an optional compile time switch (e.g. in osconfig.h) can disable the wrapper functions once application code is updated.

Fix OSAL timer test ID usage

The OSAL timer test implementation assumes that timer IDs will always be issued in sequential order starting with "0". It incorrectly assumes that the timer ID will be suitable for an array index.

An intermediate lookup table is required here, which has OS_MAX_TIMERS entries, to correctly map the ID supplied during the create call back to a local array index.

More lenient operation when "SIMULATION" compile-time directive is defined

When using the POSIX OSAL implementation under Linux, certain things only fully work when running as root. Specifically:

• Attempts to create POSIX queues at depths greater than /proc/sys/fs/mqueue/msg_max (typically 10) will fail.
• Attempts to raise the priority of user threads will fail.

The queue depth issue in particular is so frequently encountered that there is a special message printed if queue creation fails. However, the suggested workarounds require root access, and this would not typically be the case when using an official ACES-issued Linux workstation (unless one has elevated privileges).

In order to make it easier for someone to initially get up and running with OSAL/CFE, the OSAL should be more lenient and allow the operation to succeed even if all the parameters were not met due to being a normal user and not root.

A workaround such as this can be employed if and only if compiling with the "SIMULATION" flag, as this indicates the user is performing a debug build and not running on a real target. This way, the operation will still fail when performing a build for real hardware.

OS_ModuleLoad() 2nd and 3rd args need to be const

The current integration candidate for CFS_CFE includes code
that passes (char const *) pointers as the 2nd and 3rd
parameters to the OS_ModuleLoad() function. In order for this
to compile without warnings, these parameters of this function
need to carry const qualifiers in the header defining the
function and in the function itself.

The function does not modify data pointed at by these
parameters, so the const qualifier is appropriate.

This change does not require changes to callers (but does
allow them to pass pointers to const data).

This change will need to be included in the 2015-03-10
integration candidate synchronized across all projects.

( I thought I had seen a ticket for this, but was unable
to lay hands on it. )

Stand-alone posix-ng coverage test fails to build

Describe the bug
Posix-ng coverage tests fail to make

To Reproduce
Steps to reproduce the behavior:
From a clean directory with BASE_DIR=(your cFS base directory)

cmake -DOSALCOVERAGE_TARGET_OSTYPE='posix-ng' $BASE_DIR/osal/src/unit-test-coverage/
make

builds up to making ut_posix-ng_osapi with the following error:

[ 42%] Building C object posix-ng/modules/CMakeFiles/ut_posix-ng_osapi.dir/src/ut-osapi.c.o
cd /home/jhageman/cFS/osal_test_dir/posix-ng/modules && /usr/bin/cc  -D_UNIT_TEST_ -I/home/jhageman/cFS/cFS-GitHub/osal/src/unit-test-coverage/ut-stubs/inc/overrides -I/home/jhageman/cFS/cFS-GitHub/osal/ut_assert/inc -I/home/jhageman/cFS/cFS-GitHub/osal/src/os/inc -I/home/jhageman/cFS/cFS-GitHub/osal/src/bsp/pc-linux/config -I/home/jhageman/cFS/cFS-GitHub/osal/src/os/shared -I/home/jhageman/cFS/cFS-GitHub/osal/src/os/portable -I/home/jhageman/cFS/cFS-GitHub/osal/src/unit-test-coverage/ut-stubs/inc -I/home/jhageman/cFS/cFS-GitHub/osal/src/os/posix-ng  -D_LINUX_OS_   -Wall -Werror -pg --coverage -o CMakeFiles/ut_posix-ng_osapi.dir/src/ut-osapi.c.o   -c /home/jhageman/cFS/cFS-GitHub/osal/src/unit-test-coverage/posix-ng/modules/src/ut-osapi.c
/home/jhageman/cFS/cFS-GitHub/osal/src/unit-test-coverage/posix-ng/modules/src/ut-osapi.c:9:19: fatal error: osapi.c: No such file or directory
compilation terminated.

Expected behavior
Clean build, and execute/pass with make test

Code snips
Didn't investigate

System observed on:

• cFS development server (VM)
• OS: Linux 4.4.0-146-generic
• Versions: rc-6.7.0 bundle

Additional context
N/A

Reporter Info
Jacob Hageman/NASA-GSFC

Adjust usage of feature support macros for glibc/posix

Glibc (de-facto standard C library for GNU/Linux) uses compiler macros to select features from the various C standards out there.

At a bare minimum, the POSIX build currently relies on some features in XPG5 and POSIX.1c (1995).

In order to ensure these are enabled, the osapi.c file #defines "USE_UNIX98" immediately before including pthread.h. This is not the proper way to do this -- USE_UNIX98 (with underbars) is an internal macro defined by the glibc headers based on OTHER macros that were specified.

It should also be done in such a way that all source files adhere to the same general standard (for sanity sake).

== Recommended Fix ==

Use "XOPEN_SOURCE=600" across the entire build. This will enable XPG6 features. XPG6 adds some more realtime features that are likely to be useful to applications such as this, e.g. clock_nanosleep() and some others.

API additions to formalize common routines in OSAL

During unit testing and for "restart" actions in a real system (either processor or power-cycle restarts) it is necessary to have a method of cleanly shutting down the system.

Currently, support for shutdown operations is left up to the BSP, and it is not consistently handled between the various BSPs or not handled at all in some cases.

OSAL needs to have formal procedures for a normal shutdown since there is often some clean up work to do, including but not limited to:

• Sanely exit all running tasks, or collect resources from tasks that have exited already
• Delete queues, mutexes and semaphores (this is particularly necessary on systems where this is a limited resource and may affect the ability to implement a warm restart)
• Unmount any non-volatile filesystems that may have been mounted
• Delete shared memory segments

This ticket will add some basic API calls to formalize the procedure and provide the hooks necessary to do this cleanup.

The POSIX layer needs this with the highest priority, as it is used extensively for testing where a sane shutdown/restart procedure is important.

pthread_create 3rd arg must be of right type

OS_TaskCreate is handed an OSAL entry point, which is a
pointer to a function taking no parameters and returning
no return value. It passes it along to pthread_create
which is expecting a pointer to a function that takes
a single void pointer parameter, and returns a void pointer
return value.

The code as written triggers a compiler warning that we
want to get rid of.

Casting the pointer gets rid of the warning, at the cost
of presuming that the ABI will do the right thing when
the caller and callee disagree on the function signature.
This has an associated technical debt: every implementation
that uses this code has to be aware of the issue and
assure that this kind of signature mismatch is OK.

Alternately, we can stash the pointer to the entry point
somewhere, and hand pthread_create a pointer to a function
of correct type, which is responsible for calling the
entry point and returning a pointer. This has a runtime
memory cost of one stack frame.

Doing nothing retains the potential failure, but also retains
a warning about the potential failure. I suggest either doing
the real fix, or leaving the code alone until -Werror forces
us to do the real fix.

I will not automatically push this into the 2015-03-10
integration candidate, as tempted as I am.

Make OSAL tests more autonomous

The OSAL tests (in the "tests" directory, NOT "unit-test") provide reasonable "black-box" style testing of the OSAL features via the public API. However they are currently implemented with the expectation of being explicitly run by a user at the console, not from an automated script:

• Most run infinitely, requiring a CTRL+C to stop the test
• They do not count errors or provide a status code to indicate whether the test worked as expected or not.

In order to integrate with a continuous integration system, these tests need to be more automated.

This ticket is to add a "script-mode" feature to the tests which:

• Checks for the expected conditions and maintains an error counter of any tests that did not satisfy expected conditions
• Limits the time of execution and exits the test automatically (no CTRL+C)
• Returns a non-zero exit code if any errors occurred (for scripting)

(Note: this does not apply to the "unit-tests" directory which is more white-box style code coverage testing -- this will possibly need other tweaks to work with a CI system and that is a separate ticket)

Enhanced build system for OSAL

This ticket is for the OSAL portion of the enhanced build system pushed out under the corresponding cFS ticket:

​[https://babelfish.arc.nasa.gov/trac/cfs_cfe/ticket/1]

The CMake script for OSAL can also be used to generate a standalone OSAL library for use with projects other than CFS

Add free-run tick counter API to OSAL

Many times it is simpler and more efficient to deal with a simple free-running tick counter than to deal with the full-blown time API. On some OS platforms this is as simple as reading an internal timer tick register, but in the worst case it can always be generated from gettimeofday() or whatever the OS_GetLocalTime() already uses.

The OSAL currently has an API call for OS_GetLocalTime() that fills in an OS_time_t structure. The problem with this structure is that it has two parts, seconds and microseconds, which makes it difficult to add and subtract from other OS_time_t structures. Even if this were C++ and the code could be "hidden" behind an overloaded +/- operator, there is still the issue of an extra function call and checking for overflow which makes it slow and inefficient no matter how you mask it.

It can be argued that the majority of client code that calls functions such as this are really interested in "relative" time i.e. the amount of time elapsed since some prior event, as this is how timeouts and error handling are typically invoked.

A simpler way to solve this is via a single ever-incrementing (free-running) integer counter that simply increments each period and wraps around if INT_MAX is reached. The major advantage is fast and simple add/subtract/compare operations to acquire relative times. The disadvantage is that it is not easy to display as a human-readable time but this is typically not a problem -- the OS_GetLocalTime works for this. It also is not able to measure relative times more than 2^31^ ticks (about 24.8 days for 1ms period), but if time spans that long need to be measured then typically a 1-second resolution is preferable anyway and that is already available via OS_GetLocalTime().

As this is a new API call, it will not affect any existing code, it only provides a new call to simplify operations where it is more appropriate than OS_GetLocalTime().

Improve Bamboo builds of cFS OSAL tree

The current Bamboo plan for the cfs_osal project compiles OSAL and runs both sets of tests, but only recovers test results from one of the two sets. Work needs to be done to extend the test results recapture to pull in the results of the other tests.

Do not block synchronous hardware-generated signals in pc-linux BSP

As of OSAL 4.1, all signals are blocked during execution of the OS_Application_Startup() call, then unblocked before entering the wait loop.

There is some valid logic behind this --

• By definition, a signal is directed to a process, not a thread. In a multi-threaded process, each thread gets its own signal mask and "normal" signals may be delivered to any thread within that process that has the signal unmasked.
• By masking all signals during OS_Application_Startup(), any threads created during this time will automatically inherit the mask and therefore have all signals blocked.
• Signals will then be unblocked only in the original (main) thread, therefore any signals generated will be delivered only to this thread.

The issue here is that some signals on Linux are generated by the underlying hardware and the kernel forwards these (synchronously) to the specific thread that was executing on the CPU when the actual signal was triggered.

The set of hardware-generated signals: SIGSEGV, SIGILL, SIGBUS, SIGFPE should NOT be blocked at any time by any thread.

For instance, if a thread causes a segmentation fault by using a bad pointer while SIGSEGV is blocked, the thread will continue running, but results are undefined.