Chapter 4 INTEGRITY Platforms

4.1 Building Applications for INTEGRITY Platforms

First, see the basic instructions in Chapter 2 Building Applications—Notes for All Platforms.

4.1.1 Required Libraries and Compiler Flags

Table 4.1 Building Instructions for INTEGRITY Architectures lists the compiler flags and the libraries you will need to link into your application.

Depending on which Connext features you want to use, you may need additional libraries; see 4.1.3 Additional Libraries for Other Features.

Make sure you are consistent in your use of release and debug versions of the libraries. Do not mix release and debug libraries.

Release and Debug Terminology:

Both release and debug versions of the libraries are provided. For Connext, debug libraries are created with debug symbols to facilitate debugging with debugger, for example. Release libraries do not contain debug information.

The Connext debug libraries are intended solely for development and debugging purposes. These libraries are not optimized for performance or resource consumption and may include additional diagnostic information that can affect runtime behavior. They are not intended for use in production environments. Please ensure that only the release libraries are used in production deployments. Debug libraries can be identified by the suffix "d" in their names.

Table 4.1 Building Instructions for INTEGRITY Architectures

API	Library Format	Required RTI Libraries1 Choose *cpp*.* for the Traditional C++ API or *cpp2*.* for the Modern C++ API., 2 The *.dba files contain the debugging information. You can link without these, as long as they are located in the same directory as the matching *d.a file (so that the MULTI® IDE can find the debug information)., 3 The RTI C/C++ libraries are in $(NDDSHOME)/lib/<architecture>.	Required System Libraries4 Transports (other than the default IP transport) such as StarFabric may require linking in additional libraries. For further details, see the API Reference HTML documentation or contact support@rti.com.	Required Compiler Flags
C++ (Traditional and Modern APIs)	Release	libnddscorez.a libnddscz.a libnddscppz.a or libnddscpp2z.a librticonnextmsgcppz.a or librticonnextmsgcpp2z.a	libsocket.a libnet.a libposix.a	-DRTI_INTY --exceptions
	Debug	libnddscorezd.a libnddsczd.a libnddscppzd.a or libnddscpp2zd.a librticonnextmsgcppzd.a or librticonnextmsgcpp2zd.a (libnddscorezd.dba) (libnddsczd.dba) (libnddscppzd.dba or libnddscpp2zd.dba) (librticonnextmsgczd.dba)
C	Release	libnddscorez.a libnddscz.a librticonnextmsgcz.a
	Debug	libnddscorezd.a libnddsczd.a librticonnextmsgczd.a (libnddscorezd.dba) (libnddsczd.dba) (librticonnextmsgczd.dba)

4.1.2 Required Patch for INTEGRITY 11.0.4 Platforms

For INTEGRITY 11.0.4 platforms, you must install this patch from Green Hills Software:

p4080Inty11.devtree-fsl-e500mc.comp2013.5.4: patch_8154.iff, patch_8155.iff, patch_8246.iff

For more information on the patch, please contact your Green Hills Software representative.

4.1.3 Additional Libraries for Other Features

This section discusses libraries for features that are not supported for every platform. Please refer to Supported Platforms in the RTI Connext Core Libraries Release Notes to see if these libraries are supported on your platform.

Make sure you are consistent in your use of debug and release versions of the libraries. For example, if your Connext application is linked with the release version of the Connext libraries, you will need to also use the release version of the library.

4.1.3.2 Libraries Required for Monitoring

Notes: 

• The RTI library in Table 4.3 Additional Libraries for Using Monitoring must appear first in the list of libraries to be linked.
• Automatic loading of the dynamic monitoring library through QoS is not supported.
• Memory and CPU usage is not available in monitoring data.

Table 4.3 Additional Libraries for Using Monitoring

Library Format	Monitoring Libraries6 These libraries are in <NDDSHOME>/lib/<architecture>.
Static Release	librtimonitoringz.a
Static Debug	librtimonitoringzd.a

4.1.3.3 Libraries Required for Real-Time WAN Transport

If you choose to use RTIReal-Time WAN Transport, you must download and install a separate package that contains the transport libraries. See the RTI Real-Time WAN Transport Installation Guide for details.

Using Real-Time WAN Transport requires using one of the libraries in Table 4.4 Additional Libraries for Using RTI Real-Time WAN Transport APIs. Select the file appropriate for your chosen library format.

For more information, see Enabling Real-Time WAN Transport, in the RTI Connext Core Libraries User's Manual.

Table 4.4 Additional Libraries for Using RTI Real-Time WAN Transport APIs

Library Format	Real-Time WAN Transport Libraries7 These libraries are in <NDDSHOME>/lib/<architecture>.
Static Release	libnddsrwtz.a
Static Debug	libnddsrwtzd.a

4.1.3.4 Libraries Required for Zero Copy Transfer Over Shared Memory

To use the Zero Copy Transfer Over Shared Memory feature, link against the additional library in Table 4.5 Additional Libraries for Zero Copy Transfer Over Shared Memory.

Table 4.5 Additional Libraries for Zero Copy Transfer Over Shared Memory

Library Format	Zero Copy Transfer Over Shared Memory Libraries8 These libraries are in <NDDSHOME>/lib/<architecture>.
Static Release	libnddsmetpz.a
Static Debug	libnddsmetpzd.a

4.2 Running User Applications

There are no extra environment variables that must be set at run time.

4.3 Thread Configuration

4.3.1 Thread Settings and Thread-Priority Definitions

See these tables:

• Table 4.6 Thread Settings for INTEGRITY Platforms
• Table 4.7 Thread-Priority Definitions for INTEGRITY Platforms

Table 4.6 Thread Settings for INTEGRITY Platforms

Applicable Thread	DDS_ThreadSettings_t	Platform-Specific Setting
Asynchronous Publisher, Asynchronous flushing thread	mask	OS default thread type
	priority	16
	stack_size	64*1024
	cpu_list	CPU core affinity not supported
	cpu_rotation	CPU core affinity not supported
Database thread	mask	DDS_THREAD_SETTINGS_STDIO
	priority	60
	stack_size	64*1024
	cpu_list	CPU core affinity not supported
	cpu_rotation	CPU core affinity not supported
Event thread	mask	DDS_THREAD_SETTINGS_STDIO | DDS_THREAD_SETTINGS_FLOATING_POINT
	priority	80
	stack_size	4*64*1024
	cpu_list	CPU core affinity not supported
	cpu_rotation	CPU core affinity not supported
ReceiverPool threads	mask	DDS_THREAD_SETTINGS_STDIO
	priority	100
	stack_size	4*64*1024
	cpu_list	CPU core affinity not supported
	cpu_rotation	CPU core affinity not supported

Table 4.7 Thread-Priority Definitions for INTEGRITY Platforms

Thread-Priority Definition	Operating-System Priority
THREAD_PRIORITY_DEFAULT	16
THREAD_PRIORITY_HIGH	120
THREAD_PRIORITY_ABOVE_NORMAL	100
THREAD_PRIORITY_NORMAL	90
THREAD_PRIORITY_BELOW_NORMAL	80
THREAD_PRIORITY_LOW	60

4.3.2 Socket-Enabled and POSIX-Enabled Threads are Required

On INTEGRITY platforms, Connext internally relies on the POSIX API for many of its system calls. As a result, any thread calling Connext must be POSIX-enabled. By default, the 'Initial' thread of an address space is POSIX-enabled, provided the address space has been linked with libposix.a. Additional user threads that call Connext must be spawned from the Initial thread using pthread_create. Only then is the created thread also POSIX-enabled. Note that tasks created at build time using the Integrate utility are not POSIX-enabled.

Furthermore, threads calling Connext must be socket-enabled. This can be achieved by calling InitLibSocket() before making any Connext calls and calling ShutdownLibSocket before the thread terminates. Note that an Initial thread is, by default, socket-enabled when the address space is linked with libsocket.a. Please refer to the INTEGRITY Development Guide for more information.

4.3.3 Automatic Thread-Specific Storage Cleanup

INTEGRITY systems support automatic thread-specific storage cleanup. Use of the DomainParticipantFactory::unregister_thread API is therefore not required to clean up thread-specific storage in user threads (although it is safe to do so).

4.4 Socket Buffer Size Configuration

See Table 4.8 UDP send_socket_buffer_size and Table 4.9 UDP receive_socket_buffer_size. For more information on the send_socket_buffer_size and receive_socket_buffer_size properties, see Setting Builtin Transport Properties with the PropertyQosPolicy, in the RTI Connext Core Libraries User's Manual.

Table 4.8 UDP send_socket_buffer_size

Property	Behavior
NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT	Uses the default send socket buffer size
NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_MAX	Not supported (NDDS_TRANSPORT_UDPV4_SEND_SOCKET_BUFFER_SIZE_DEFAULT will be used)
NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_DEFAULT	Uses the default send socket buffer size
NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_MAX	Not supported (NDDS_TRANSPORT_UDPV6_SEND_SOCKET_BUFFER_SIZE_DEFAULT will be used)

Table 4.9 UDP receive_socket_buffer_size

Property	Behavior
NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_DEFAULT	Uses the default receive socket buffer size
NDDS_TRANSPORT_UDPV4_SOCKET_BUFFER_SIZE_OS_MAX	Not supported (NDDS_TRANSPORT_UDPV4_RECV_SOCKET_BUFFER_SIZE_DEFAULT will be used)
NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_DEFAULT	Uses the default receive socket buffer size
NDDS_TRANSPORT_UDPV6_SOCKET_BUFFER_SIZE_OS_MAX	Not supported (NDDS_TRANSPORT_UDPV6_RECV_SOCKET_BUFFER_SIZE_DEFAULT will be used)

4.5 Running over IP Backplane on a Dy4 Champ-AVII Board

Connext can run on all four CPUs, provided the following hold true:

• Connext applications on CPUs B, C and D only exchange data with applications on a different CPU or off-board.
• The IP backplane and associated routing has been properly configured. Connext has been tested with the following libraries built into the INTEGRITY kernel: debug, res, load, socket, itcpip, lbp, queue, ifbp, idb, bsl.

4.6 Out-of-the-box Transport Compatibility with Other Connext Platforms

Due to some default kernel parameters on INTEGRITY platforms, the default value for message_size_max for the UDPv4 transport, and the default values for message_size_max, received_message_count_max, and recv_buffer_size for the shared-memory transport, are different than those for other platforms. This will cause out-of-the-box compatibility issues that may result in lack of communication. The mismatch in transport configuration between INTEGRITY and other platforms applies to Connext 5.1.0 and higher. For more information, see the "Transport Compatibility" section in the RTI Connext Core Libraries Release Notes for 5.3.1.

To address the compatibility issues, you can change the default transport settings of other platforms to match those of the INTEGRITY platform. Alternatively, you can update the INTEGRITY kernel parameters as described below so that the INTEGRITY platform will support larger transport settings.

The directive, GM_IP_FRAG_ENTRY_MAX_SIZE, limits the size of UDP packets that can be sent and received by INTEGRITY platforms. For details on this directive, please see Section 5.4.2 in the networking.pdf manual provided with the INTEGRITY kernel. The default value of GM_IP_FRAG_ENTRY_MAX_SIZE is 9216 bytes (not 16,000 bytes as is stated in the INTEGRITY documentation), which is why the default message_size_max for all transports supported for INTEGRITY is 9216 bytes.

If you want to send UDP messages larger than 9k, you must increase the value of GM_IP_FRAG_ENTRY_MAX_SIZE and rebuild the kernel. (You may also have to reconfigure other kernel parameters such as the socket, stack, and heap sizes to accommodate the larger value for GM_IP_FRAG_ENTRY_MAX_SIZE.) Failing to increase this value will cause failures when sending large UDP packets, and in some cases the sendto() call will fail silently.

4.6.1 Smaller Shared-Memory Receive-Resource Queue Size

INTEGRITY's shared-memory pluggable transport uses the shared-memory POSIX API. This API is part of the standard INTEGRITY distribution and is shipped as a library. This library uses a hard-coded value for the total amount of memory that can be shared with an address space. This limits the overall buffer space that can be used by the DomainParticipants within the same address space to communicate over shared memory with other DomainParticipants.

To allow more DomainParticipants to run within the same address space, we reduced the default size of the queue for each receive resource of the shared memory transport. The queue size is reduced to eight messages. This change only applies to INTEGRITY architectures and this default value can be overwritten through the shared memory transport QoS.

4.6.2 Using Shared Memory on INTEGRITY Systems

Connext uses the single address-space POSIX library to implement the shared-memory transport on INTEGRITY operating systems.

To clean up shared memory resources, reboot the kernel.

To use shared-memory, you must configure your system to include the POSIX shared-memory library. The posix_shm_manager must be running in an "AddressSpace" solely dedicated to it. After building any Connext application that uses shared memory, you must use the intex utility (provided with the INTEGRITY development environment) to pack the application with multiple address-spaces: one (or more) to contain the Connext application(s), and another one to contain the posix_shm_manager.

Connext will run on a target without the posix_shm_manager, but the POSIX functions will fail and return ENOSYS, and the participants will fail to communicate through shared memory.

To include the POSIX Shared-Memory Manager in its own Address Space:

The project files generated by rtiddsgen for MULTI will create the shared-memory manager for you. Please follow these steps:

1. Specify the path to your INTEGRITY distribution in the _default.gpj top-level project file by adding the following line (modify it according to the path to your INTEGRITY distribution):

-os_dir=/local/applications/integrity/integrity-10.0.2 

2. Build the project.
3. Before running your Connext application on a target, download the posix_shm_manager file (generated by the build) onto the target.

The POSIX Shared Memory Manager will start automatically after the download and your applications will be able to use shared memory.

Notes:

• Only one posix_shm_manager is needed on a particular target. INTEGRITY offers the option of building this posix_shm_manager inside the kernel. Please refer to the INTEGRITY documentation.
• If you are already using shared memory through the POSIX library, there may be a possible conflict.
• INTEGRITY has two different types of POSIX libraries: a single-address space one (or 'light') and another one (complete POSIX implementation). Connext uses the first one, but will work if you are using the complete POSIX implementation.

4.6.3 Shared Memory Limitations on INTEGRITY Systems

If several applications are running on the same INTEGRITY node and are using shared memory, once an application is stopped, it cannot be restarted. When the application is stopped (gracefully or ungracefully), any new application on the same domain index within the same DDS domain will fail to start until the shared memory manager is also restarted.

Additionally, if the application is stopped ungracefully, the remaining applications will print several error messages such as the following until Connext purges the stopped application from its database:

Resource Manager send error = 0x9

This error message is logged from INTEGRITY’s POSIX shared memory manager, not from Connext. The error message is benign and will not prevent the remaining applications from communicating with each other or with application on other nodes.

The workaround is to either restart the stopped application with a different participant index or shut down all the other applications and the shared memory manager, then restart everything.

4.7 Using rtiddsping and rtiddsspy on INTEGRITY Systems

While the RTI libraries for INTEGRITY can be used with any BSP, providing the processor falls under the same category (for example, the ppc7400... RTI libraries can be used on any target with a PPC74xx processor), rtiddsping and rtiddsspy are provided as executables, and therefore are BSP-dependent. You will not be able to run them successfully on your target if it is not compatible with the BSP listed in the architecture name (such as pcx86-smp). In this case, you will need to re-integrate the rtiddsping and rtiddsspy applications. Please refer to your hardware documentation for peripheral compatibility across BSPs.

4.8 Issues with INTEGRITY Systems

4.8.1 Delay When Writing to Unreachable Peers

On INTEGRITY systems, if a publishing application’s initial peers list includes a nonexistent (or simply unreachable) host, calls to write() may block for approximately 1 second.

This long block is caused by the stack trying to resolve the invalid/unreachable host. Most IP stacks do not block the sending thread because of this reason, and you may include invalid/unreachable hosts in your initial-peers list. If you find that your stack does block the sending thread, please consult your IP stack vendor on how to change its behavior.

4.8.2 Linking with ‘libivfs.a’ without a File System

If you link your application with libivfs.a and are using a system that does not have a file system, you may notice the application blocks for 2 seconds at start-up.

4.8.3 Compiler Warnings Regarding Unrecognized #pragma Directives

Building Connext projects for INTEGRITY causes the compiler to produce several warnings about #pragma directives not recognized in some Connext header files. For example:

Building default.bld
"C:/ndds/ndds.4.4x/include/ndds/dds_c/dds_c_infrastructure.h", line 926: 
warning: unrecognized #pragma
  #pragma warning(push)
          ^
"C:/ndds/ndds.4.4x/include/ndds/dds_c/dds_c_infrastructure.h", line 927: 
warning: unrecognized #pragma
  #pragma warning(disable:4190)
          ^
"C:/ndds/ndds.4.4x/include/ndds/dds_c/dds_c_infrastructure.h", line 945: 
warning: unrecognized #pragma
  #pragma warning(pop)
          ^

These warnings do not compromise the final application produced and can be safely ignored.