5.6. Compiling the Connext Micro Source for LynxOS-178¶

5.6.1. Introduction¶

Connext Micro includes support for LynxOS-178 systems and enables Connext Micro applications to communicate using both UDP and the ARINC 653 transport. The support has been tested on the POC-310 board with a LynxOS-178 system.

This manual explains how to configure and compile Connext Micro to run on LynxOS-178 systems. Connext Micro supports both POSIX and APEX APIs from LynxOS-178, and this documentation considers both APIs.

LynxOS-178 POSIX Platform Notes

Compiling the libraries for LynxOS-178 POSIX

LynxOS-178 APEX Platform Notes

LynxOS-178 APEX Configuration

Compiling the libraries for LynxOS-178 APEX

Interoperability

5.6.2. LynxOS-178 POSIX Platform Notes¶

Connext Micro uses an abstract platform API that must be ported to different platforms. This section discusses the implementation of the platform abstractions on the LynxOS-178 POSIX platform.

Platform Initialization
Heap
Mutex
Semaphores
Timers
Time
Threads
Sockets
System configuration

5.6.2.1. Platform Initialization ¶

Before any DDS entities are created, Connext Micro must be initialized. This initialization is done by first setting the OSAPI System property, and then calling DDS_DomainParticipantFactory_get_instance().

Calling DDS_DomainParticipantFactory_get_instance() will automatically initialize Connext Micro using the OSAPI System property.

5.6.2.2. Heap ¶

Connext Micro will allocate all of its memory using malloc.

5.6.2.3. Mutex ¶

Connext Micro uses recursive mutexes to protect its critical sections. Because all Connext Micro APIs are synchronous, a mutex take operation blocks until the mutex becomes available. It is unexptected behavior if a mutex does not become available.

5.6.2.4. Semaphores ¶

Connext Micro uses a semaphore to implement the DDS WaitSet. One semaphore is implemented with a condition variable while another semaphore is implemented with an internal timer (e.g. a DDS_WaitSet with a finite duration) that signals the condition variable upon timeout.

The resolution of a semaphore is rounded up to the nearest clock tick + 1. Thus, a semaphore may take up to 2 clock ticks (at most) extra to time out. The timeout is tied to the tick-time mentioned in Timers.

Note

Connext Micro does not support multiple threads blocking on a semaphore. None of the public Connext Micro APIs would cause multiple threads to block on the same semaphore.

5.6.2.5. Timers ¶

Connext Micro implements its own software timers to support timed events such as periodic participant announcements and checking for missed deadlines.

The timer resolution for Connext Micro timers is 10 milliseconds. This cannot be changed without recompiling Connext Micro.

Connext Micro requires an external (to Connext Micro) clock tick to run its internal timers. On LynxOS-178, this clock tick is implemented with a dedicated thread. This cannot be changed.

In addition to runnning the internal timers, Connext Micro maintains an internal clock that is started when Connext Micro is first initialized, and which is incremented in each clock-tick. The clock-tick is maintained as a 32-bit signed second counter and a 32-bit unsigned nanosecond counter.

This internal clock is known as the “tick-time” and is a function of the number of clock-ticks, not the actual time. The tick-time is used to control semaphore timeout, deadline, and liveliness.

The timer subsystem is configured to use signals and semaphores to integrate with the timer thread. This cannot be changed.

5.6.2.6. Time ¶

DDS APIs use the time of day to timestamp samples. On LynxOS-178 systems, this timestamp is retrieved using gettimeofday(). Note that no check is performed on the returned time of day (such as time going backwards).

The time is also used to determine the interval between two samples when the sample ordering is per source timestamp on the DataWriter.

5.6.2.7. Threads ¶

Connext Micro creates threads to run timers and process data received from the network.

By default, threads are created with the following:

PTHREAD_EXPLICIT_SCHED attribute.
PTHREAD_CREATE_DETACHED attribute.
OS default stack size.
Priority inheritied from spawning thread.

If the OSAPI_ThreadOptions OSAPI_THREAD_REALTIME_PRIORITY is used, the following attributes are set as well:

PTHREAD_SCOPE_SYSTEM
SCHED_FIFO

Two types of thread priorties can be set:

Absolute

A priority equal to or larger than zero is used as is, and must be within the range allowed by the OS.
Calculated

A priority between [OSAPI_THREAD_PRIORITY_LOW, OSAPI_THREAD_PRIORITY_HIGH] is calculated using the following formula:
```
OS.min_priority + (((OS.max_priority - OS.min_priority) * priority_level)/OSAPI_THREAD_PRIORITY_HIGH);
```

5.6.2.8. Sockets ¶

Connext Micro creates a single socket to send data with and one socket for each receive thread created. If a multicast address is specified to receive data on, multicast loopback is automatically enabled.

5.6.2.9. System configuration ¶

More information can be found in the OS distribution documentation folder.

5.6.3. Compiling the libraries for LynxOS-178 POSIX¶

This section explains how to compile the Connext Micro source code for LynxOS-178 systems. Compilation has to be done either using rtime-make.

5.6.3.1. Compiling Connext Micro with rtime-make¶

The Connext Micro source bundle includes a bash (on Linux and macOS systems) or BAT (on Windows systems) script to simplify the invocation of CMake called rtime-make. These scripts provide a convenient way to invoke CMake with the correct options.

Make sure CMake is in the path.
Configure the build environment to setup an envvar PLATFORM_TOOLCHAIN_PATH that points to the Lynx MOSA.ic distribution root folder.
From the Connext Micro install directory, call rtime-make with the --target option. For a list of available targets, use the --list option. Please refer to Preparing for a Build for details. For example, to compile for x64:
resource/scripts/rtime-make --target LynxOS-178 --name x64Lynx1782024.09.0.POSIXgcc11.3.0 --config Release --build

The Connext Micro libraries will be available in:

<rti_me install directory>/lib/x64Lynx1782024.09.0.POSIXgcc11.3.0

5.6.4. LynxOS-178 APEX Platform Notes¶

Connext Micro uses an abstract platform API that must be ported to different platforms. This section discusses the implementation of the platform abstractions on the LynxOS-178 APEX platform.

Platform Initialization
C API Restrictions
Heap
Mutex
Semaphores
Timers
Time
Threads
Sockets

5.6.4.1. Platform Initialization ¶

Before any DDS entities are created, Connext Micro must be initialized. This initialization is done by first setting the OSAPI System property, and then calling DDS_DomainParticipantFactory_get_instance().

See LynxOS-178 APEX Configuration for how to configure the OSAPI System property. This property cannot be reconfigured after Connext Micro has been initialized.

Calling DDS_DomainParticipantFactory_get_instance() will automatically initialize Connext Micro using the OSAPI System property.

5.6.4.2. C API Restrictions ¶

The LynxOS-178 port of Connext Micro implements platform abstractions using the ARINC 653 API. This API requires that all ARINC objects are created before entering NORMAL mode. Therefore, all DDS entities must be created before a partition enters NORMAL mode.

The following C APIs can only be used before NORMAL mode:

DDS_DomainParticipantFactory_get_instance
DDS_DomainParticipantFactory_create_participant
DDS_DomainParticipant_create_publisher
DDS_DomainParticipant_create_subscriber
DDS_DomainParticipant_create_topic
DDS_Publisher_create_datawriter
DDS_Subscriber_create_datareader
DDS_GuardCondition_new
DDS_WaitSet_new

5.6.4.3. Heap ¶

Connext Micro can either allocate all of its memory using malloc or from a user provided buffer. This behavior can be configured through the OSAPI System property. See LynxOS-178 APEX Configuration for details on how to configure the heap.

5.6.4.4. Mutex ¶

Connext Micro uses recursive mutexes to protect its critical sections. On LynxOS-178 systems, mutexes are implemented using ARINC 653 semaphores. Because all Connext Micro APIs are synchronous, a mutex take operation blocks until the mutex becomes available. It is unexpected behavior if a mutex does not become available.

5.6.4.5. Semaphores ¶

Connext Micro uses semaphores to implement the DDS WaitSet. A DDS WaitSet with a timeout calls WAIT_SEMAPHORE() with the timeout value directly, and the timeout precision is determined by WAIT_SEMAPHORE().

Note

Connext Micro does not support multiple threads blocking on a semaphore. None of the public Connext Micro APIs would cause multiple threads to block on the same semaphore.

5.6.4.6. Timers ¶

Connext Micro implements its own software timers to support timed events such as periodic participant announcements and checking for missed deadlines.

The timer resolution for Connext Micro timers is equal to the period of the OSAPI System timer thread. This thread can be configured through the OSAPI System Timer Thread Property.

In addition to running the internal timers, Connext Micro maintains an internal clock that is started when Connext Micro is first initialized, and which is incremented in each clock-tick. The clock-tick is maintained as a 32-bit signed second counter and a 32-bit unsigned nanosecond counter.

This internal clock is known as the “tick-time” and is a function of the number of clock-ticks, not the actual time. The tick-time is used to control semaphore timeout, deadline, and liveliness.

For LynxOS-178 systems, the “tick-time” starts incrementing when the OSAPI System timer thread first executes. The timer thread is implemented as an ARINC process which will automatically start when the partition switches to NORMAL mode. The exact timing for when this thread starts depends on the process’s priority and the on the other processes in the partition.

5.6.4.7. Time ¶

DDS APIs use the system clock to timestamp samples. On LynxOS-178 systems, this timestamp is retrieved using the ARINC 653 GET_TIME() API. Note that no check is performed on the returned time (such as time going backwards).

The time is also used to determine the interval between two samples when the sample ordering is per source timestamp on the DataWriter.

5.6.4.8. Threads ¶

Connext Micro creates threads to run timers and process data received from the network. On LynxOS-178 systems, threads are implemented using ARINC 653 processes.

ARINC 653 processes do not start executing until a partition enters NORMAL mode. Therefore, none of Connext Micro’s internal threads will start executing until NORMAL mode.

By default, threads are created with:

OS default stack size
OS normal thread priority
Period of INFINITE_TIME_VALUE
Time capacity of INFINITE_TIME_VALUE
SOFT deadline
Empty process name

For LynxOS-178 systems, Connext Micro defines the OS default stack size to be 128KB and OS normal thread priority to be 98.

5.6.4.9. Sockets ¶

Connext Micro does not have access to datagram oriented communications when using APEX API.

For details on how to use the ARINC 653 transport, please refer to the ARINC 653 Transport documentation.

5.6.5. LynxOS-178 APEX Configuration¶

The OSAPI System Property must be set before any other call to a Connext Micro API. This is done by using OSAPI_System_get_property() to get the property, then making the necessary changes, and finally setting the property with OSAPI_System_set_property().

/* Example application configuration of OSAPI System Property */

struct OSAPI_SystemProperty osapi_sys_prop;

/* Get the OSAPI_SystemProperty */
if (!OSAPI_System_get_property(&osapi_sys_prop))
{
    /* Handle failure condition */
}

/* Configure OSAPI System A653 Port Property */
osapi_sys_prop.port_property.parent.max_threads = 32;

/* Configure OSAPI System Lynx178 Port Property */
osapi_sys_prop.port_property.timer_resolution = 100;

/* Configure OSAPI System Timer Thread */
osapi_sys_prop.timer_property.thread.port_property.parent.period = INFINITE_TIME_VALUE;
osapi_sys_prop.timer_property.thread.port_property.parent.time_capacity= INFINITE_TIME_VALUE;
osapi_sys_prop.timer_property.thread.port_property.parent.deadline = SOFT;
osapi_sys_prop.timer_property.thread.stack_size = 32000;
osapi_sys_prop.timer_property.thread.priority = 99;
strcpy(osapi_sys_prop.timer_property.thread.port_property.parent.name, "rti.timer_thread");

if (!OSAPI_System_set_property(&osapi_sys_prop))
{
    /* Handle failure condition */
}

5.6.5.1. OSAPI System Port Property¶

The OSAPI System Port Property defines parameters related to how resources are pre-allocated for the ARINC 653 OSAPI implementation. If heap_base_address is NULL, then Connext Micro will allocate memory using malloc. Optionally, an application can allocate memory itself and give it to Connext Micro by setting heap_base_address to be a pointer to the start of the buffer. If specifying a heap_base_address, the buffer’s size must be defined in the port property heap_size. If heap_base_address is NULL, the value of heap_size` is ignored. The maximum number of threads needs to be defined in max_threads so that memory can be allocated to store thread information.

Aside from that, Connext Micro will need to be provided with the only LynxOS-178-specific property, the timer resolution. The ARINC 653 system time will be based on the LynxOS-178 high-resolution clock, that it is platform dependent and on most boards will provide sub-micro second resolution. This value has to match the number of nanoseconds it takes for the Connext Micro internal software clock to tick. This value will impact on the reliability of the library.

5.6.5.2. OSAPI System Timer Thread Property¶

Connext Micro uses a timer thread to manage all the Connext Micro timers, such as deadline and liveliness timers. This thread must be run at a constant period. If the thread period is set to INFINITE_TIME_VALUE, then it will execute at the configured timer resolution frequency. Note that the priority of this task must be set based on the required system behavior.

5.6.6. Compiling the libraries for LynxOS-178 APEX¶

This section explains how to compile the Connext Micro source code for LynxOS-178. Compilation has to be done either using rtime-make.

5.6.6.1. Compiling Connext Micro with rtime-make¶

The Connext Micro source bundle includes a bash (on Linux and macOS systems) or BAT (on Windows systems) script to simplify the invocation of CMake called rtime-make. These scripts provide a convenient way to invoke CMake with the correct options.

Make sure CMake is in the path.
Configure the build environment to setup an envvar PLATFORM_TOOLCHAIN_PATH that points to the GHS OS and Compiler distribution root.
From the Connext Micro install directory, call rtime-make with the --target option. For a list of available targets, use the --list option. Please refer to Preparing for a Build for details. For example, to compile for the Kontron COMe-cTL6:

..code-block:: console

resource/scripts/rtime-make –target Lynx178 –name x64Lynx1782024.09.0.APEXgcc11.3.0 –config Release –build

The Connext Micro libraries will be available in:

<rti_me install directory>/lib/x64Lynx1782024.09.0.APEXgcc11.3.0

5.6.7. Interoperability¶

The Connext Micro LynxOS-178 port does not have any additional restrictions regarding interoperability; the same considerations apply as for other ports. For more information, please refer to Working with RTI Connext Micro and RTI Connext.