2.1. General Compatibility 6.1.0¶
This section describes compatibility issues that affect the Connext suite in Release 6.1.0. Unless noted otherwise, the issues in this section do not apply to Connext DDS Micro.
2.1.1. Platforms¶
2.1.1.1. New and Removed Platforms¶
For information on new and removed platforms in this release, see What’s New in 6.1.0. See also individual products’ Release Notes.
2.1.1.2. New Linux® Linker Flag¶
For GCC 6 or higher, there is a new required linker flag for compiling:
-no-pie
. See the “Building Instructions for Linux Architectures” table in the
Core Libraries Platform Notes for more information.
2.1.1.3. Additional Build Flags for Backtrace Feature¶
Additional build flags, including -rydynamic
, are now required for a proper debug
build using the backtrace feature. (Backtrace support was added in 6.0.1 and
enhanced in 6.1.0.) If these flags are not included, some details
like the line number associated with each stack frame may not be available.
For further details, look for “Backtrace Support” for your operating system in the
Core Libraries Platform Notes.
2.1.1.4. VxWorks Installation Changes¶
In previous releases, VxWorks® libraries came in one target package, such as
rti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3.rtipkg
. In this release,
the VxWorks targets come in separate files, one for the kernel libraries and
one for the rtp libraries:
rti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3.rtipkg
for kernelrti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3_rtp.rtipkg
for rtp
The rtp libraries are now packaged/installed separately from the kernel package.
2.1.1.5. VxWorks Library Name Changes¶
In VxWorks rtp architectures, the names of the utilities are now suffixed with a
“z” to indicate that they are statically linked: RTI DDS Ping is called
rtiddspingz.vxe
, RTI DDS Spy is called rtiddsspyz.vxe
, and RTI DDS
Prototyper is called rtiddsprototyperz.vxe
.
For more information, see Using DDS Ping and Spy, in the Getting Started Guide Addendum for Embedded Systems.
2.1.2. Wire Compatibility¶
2.1.2.1. RTPS Versions¶
See Section 4.1.2.1 for information about the RTPS versions supported for each Connext DDS release.
2.1.2.2. Protocol Changes¶
2.1.2.2.1. New RTPS BINDING_PING submessage when using RTI Real-Time WAN Transport¶
Real-Time WAN Transport uses special RTPS messages called BINDING_PING messages
to open NAT bindings and to resolve endpoint locators into public IP transport
addresses. These messages are sent periodically at a period configured by the
parameter <binding_ping_period>
, in <transport_builtin>/<udpv4_wan>
.
For additional information, see RTI Real-Time WAN Transport, in the RTI Connext DDS Core Libraries User’s Manual.
2.1.2.2.2. Changes to PID_DIRECTED_WRITE inline QoS parameter¶
The OMG RTPS 2.3 specification defines the GUID in a PID_DIRECTED_WRITE inline QoS parameter as a <GUID_t>. Previous releases incorrectly serialized the GUID as four integers in native endianness, as opposed to an array of 16 bytes. To conform with the specification, Connext DDS now serializes the GUID as an array of 16 bytes.
To avoid breaking backward compatibility with previous releases, the GUID is still serialized natively when the remote DomainParticipant has an older Connext DDS product version.
2.1.2.2.3. New DATA_FRAG_SESSION submessage when using fragmentation with MultiChannel DataWriters¶
MultiChannel DataWriters (including DataWriters of TopicQuery samples) send fragmented data using a new RTPS submessage called DATA_FRAG_SESSION (submessage ID: 0x81). It is similar to DATA_FRAG, except that there is an additional virtual sequence number field in the submessage.
Important
This protocol change breaks compatibility with previous releases. A DataReader in a previous release cannot receive MultiChannel or TopicQuery RTPS fragmented data from a DataWriter in 6.1.0. See Section 2.1.2.3 for additional information.
2.1.2.2.4. New bit in PID_VENDOR_BUILTIN_ENDPOINT_SET sent with DATA(P) messages¶
This release introduces a new bit, RTPS_VENDOR_BUILTIN_ENDPOINT_CDS_ANNOUNCER_WRITER (0x00000001 << 6), into the PID_VENDOR_BUILTIN_ENDPOINT_SET parameter sent with DATA(P) messages to indicate that the DATA(P) message is coming from Cloud Discovery Service.
2.1.2.2.5. Extension to DATA_REPRESENTATION PID¶
The compression QoS settings are included as part of the
DATA_REPRESENTATION QosPolicy
and are used for endpoint matching during discovery. In general, Connext DDS attempts to
save bandwidth during endpoint discovery by only propagating QoSs that are set differently
from an assumed default value. In the case of compression_ids
, if they are not sent
during endpoint discovery, the assumed default is that the endpoint (DataWriter or DataReader) does
not support any compression algorithms. The default setting for a DataReader, however, is to
support all available builtin compression algorithms, meaning that the compression_ids
,
and therefore the entire DataRepresentationQosPolicy, is sent by default in the
SubscriptionBuiltinTopicData. This adds an additional 16 bytes to the
SubscriptionBuiltinTopicData by default. Setting a DataReader’s compression_ids
to
COMPRESSION_ID_MASK_NONE
gets rid of these additional bytes.
When compression_ids
are sent to endpoints (DataWriters and DataReaders) during discovery, the
additional number of bytes sent is as follows:
4 bytes for the QoS mutable header:
2 bytes for parameterId
2 bytes for parameterLength
6 bytes for the struct DDS_DataRepresentationIdSeq value:
4 bytes of sequence length
2 bytes of default sequence value (short integer)
2 bytes for padding
4 bytes for DDS_CompressionIdMask
compression_ids
(dds ulong)
TOTAL = 16 Bytes
2.1.2.2.6. New inline QoS Parameters for coherent set samples¶
6.1.0 introduces support for coherent access with group presentation (see What’s New in 6.1.0). This feature adds the following inline parameters sent with samples that are part of a coherent set:
PID_END_COHERENT_SET (0x8022): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the sequence number of the first sample update belonging to the coherent set from the DataWriter publishing the sample. The size of this parameter is 12 bytes.
PID_GROUP_COHERENT_SET (0x0063): Contains the group sequence number of the first sample update belonging to the coherent set across all DataWriters within the Publisher. The size of this parameter is 12 bytes.
PID_END_GROUP_COHERENT_SET (0x8023): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the sequence number of the first sample update belonging to the coherent set across all DataWriters within the Publisher. The size of this parameter is 12 bytes.
PID_END_COHERENT_SET_SAMPLE_COUNT (0x8024): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the number of samples contained in the coherent set for a DataWriter. The size of this parameter is 8 bytes.
2.1.2.3. DataReader in previous release cannot receive MultiChannel or TopicQuery RTPS fragmented data from DataWriter in 6.1.0¶
The fix for RTI Issue ID CORE-9335 required breaking backward compatibility with the existing support for RTPS data fragmentation with MultiChannel and TopicQuery. This means that you will not be able to have a DataReader from a previous release receiving MultiChannel or TopicQuery RTPS fragmented data from a 6.1.0 DataWriter.
2.1.3. Type System Compatibility¶
2.1.3.1. Connext DDS applications from previous releases will not interoperate with 6.1.0 and later, for types containing optional primitive members, when data representation is XCDR2¶
In previous releases, a bug (RTI Issue IDs CORE-10254 and MICRO-2307) led to an incorrect XCDR2 serialization of samples for a type with the following properties:
The type had a primitive member ‘Pn’ (it could be external but not optional) following another primitive member ‘Pn-1’ that was marked as optional.
The required alignment for ‘Pn’ was smaller than or equal to the required alignment for ‘Pn-1’.
The optional member was set to NULL in the sample.
This issue affected both Connext DDS Micro and Connext DDS Professional. It affected the following language bindings: C, C++ (traditional and modern), and DynamicData in all languages. It affected all languages if using ContentFilteredTopics.
After fixing this issue, Connext DDS applications from before 6.1.0 will not interoperate with Connext DDS applications 6.1.0 and later, for Topics using the types with the properties described above.
2.1.3.2. C/C++ applications may not interoperate for keyed types under certain conditions¶
In previous releases, a bug (RTI Issue IDs CORE-11290 and MICRO-2987) led to an incorrect XCDR (Extensible CDR version 1) instance keyhash generation for C/C++ applications.
This issue only occurred when:
The type was a keyed type containing a key member whose type was a typedef of a keyed struct/valuetype type.
The data representation was XCDR (Extensible CDR version 1).
You generated code using the command-line option
-optimization 0
.
This issue affected both Connext DDS Micro and Connext DDS Professional. It affected the following language bindings: C, C++ (traditional and modern).
After fixing this issue, C/C++ Connext DDS applications from before 6.1.0 will not
fully interoperate with Connext DDS applications 6.1.0 and later, for Topics using
the types with the properties described above. As a result, the subscribing
application may observe some unexpected behavior related to instances. Specifically,
the call to DataReader::lookup_instance()
might fail and return HANDLE NIL
even if the instance was received.
2.1.4. Transport Compatibility¶
2.1.4.1. IP Mobility events may stop communication with applications from previous releases¶
In previous releases, IP mobility events that qualified as a change (for example, the change of the IP address of one of the local interfaces) always triggered the sending of both Participant and Endpoint discovery updates to all the matched remote entities. This was true even in scenarios where, due to the nature of the change, it was enough just to send Participant Discovery updates—for example, when DataWriters and DataReaders were using the default Participant locators (as opposed to setting specific locators through TransportSelection or TransportUnicast QoS policies).
This release changes the behavior of Connext DDS in this scenario: a Participant will now only send Participant Discovery updates, saving the network bandwidth associated with sending Endpoint Discovery updates. Connext DDS will still propagate Endpoint Discovery updates in scenarios where DataWriters and DataReaders are using specific locators instead of the ones inherited from the Participant.
This change breaks backwards compatibility with pre-6.1.0 versions of Connext DDS once an IP mobility change occurs. Previous versions of Connext DDS still need to receive the redundant Endpoint Discovery traffic to process the change.
For backwards compatibility, set the property
dds.participant.discovery_config.force_endpoint_announcement_on_ip_mobility_event
to true in 6.1.0.
2.1.5. XML Compatibility¶
2.1.5.1. Summary of XML schema changes for XML-based application creation and QoS profiles¶
Release 6.1.0 introduces some changes to the XML schema for Connext DDS applications that can break XML configurations from previous releases. Table 2.1 lists the changes, which are described in more detail below.
Table 2.1 XML Tag Name Changes¶ Pre-6.1.0
6.1.0
See …
Comma-separated decimal or hexadecimal element values for
<group_data>
,<user_data>
, and<topic_data>
xs:hexBinary
format for<group_data>
,<user_data>
, and<topic_data>
The following tags …
<participant_qos>
<filter>
<parameter_list>
in<filter>
<value>
in<parameter_list>
were renamed …
<domain_participant_qos>
<content_filter>
<expression_parameters>
in<content_filter>
<element>
in<expression_parameters>
Section 2.1.5.3 (see also Section 2.2.7.1 if you are using Routing Service)
Single-type
<instance_replacement>
Complex-type
<instance_replacement>
2.1.5.2. Connext DDS applications from 6.1.0 and later may fail to parse XML configuration files from previous releases if <group_data>, <user_data>, or <topic_data> tags are used¶
Release 6.1.0 updated the type used by <group_data>
, <user_data>
, and
<topic_data>
. The new representation is an xs:hexBinary
value. The old
format, in which the content is provided as a set of comma-separated decimal or
hexadecimal element values, will still be accepted by the Connext XML parser,
except when the value contains a single byte in non-hexadecimal (0x) notation.
If a value is a single byte, the XML parser cannot tell whether the value uses
the old format or the new one xs:hexBinary
. To distinguish between them, a
new Processing Instruction, <?rti-baseformat HEX|DEC?>
, has been added.
This Processing Instruction indicates whether the format is hexadecimal or
decimal, and it is only needed when the value is a single byte in
non-hexadecimal notation.
As a result of this change, the following XML example was valid in 6.0.1, but not in 6.1.0:
<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://community.rti.com/schema/6.1.0/rti_dds_profiles.xsd">
<!-- QoS Profiles -->
<qos_library name="QosLibrary">
<qos_profile name="Base">
<participant_qos>
<user_data>
<value>10</value>
</user_data>
</participant_qos>
</qos_profile>
</qos_library>
<!-- Domains -->
<domain_library name="DomainLibrary">
<!-- Shape -->
<domain name="Shape" domain_id="0">
...
</domain>
...
</domain_library>
<!-- Participants -->
<domain_participant_library name="DomainParticipantLibrary">
<!-- Shape -->
<domain_participant name="ShapePublisher" domain_ref="DomainLibrary::Shape">
<participant_qos base_name="QosLibrary::Base">
...
</participant_qos>
...
</domain_participant>
</domain_participant_library>
</dds>
Using the above XML will produce an error similar to the following:
DDS_XMLQos_onEndOctetSequenceElement:Parse error at line XXX: processing instruction
<?rti-baseformat HEX|DEC?> missing
Pre-6.1.0 XML files that use a single byte value for <group_data>
, <user_data>
,
and <topic_data>
will need to be updated as follows by adding the new
Processing Instruction. For example:
<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://community.rti.com/schema/6.1.0/rti_dds_profiles.xsd">
<?rti-baseformat HEX?>
<!-- QoS Profiles -->
<qos_library name="QosLibrary">
<qos_profile name="Base">
<participant_qos>
<user_data>
<value>10</value>
</user_data>
</participant_qos>
</qos_profile>
</qos_library>
<!-- Domains -->
<domain_library name="DomainLibrary">
<!-- Shape -->
<domain name="Shape" domain_id="0">
...
</domain>
...
</domain_library>
<!-- Participants -->
<domain_participant_library name="DomainParticipantLibrary">
<!-- Shape -->
<domain_participant name="ShapePublisher" domain_ref="DomainLibrary::Shape">
<participant_qos base_name="QosLibrary::Base">
...
</participant_qos>
...
</domain_participant>
</domain_participant_library>
</dds>
In the above example, the type of <user_data>
will be considered xs:hexBinary
.
The old format is still accepted by the Connext XML parser, but it will fail
validation with the XSD schema. Therefore, even if an XML file with the old format
is accepted by the parser, you should transition to the new xs:hexBinary
format, because the XSD schema for QoS profiles will fail to validate the old format.
Infrastructure Services use XSD validation to verify the correctness
of the input configuration file, and they will fail to load an XML configuration
using the old format. In RTI Routing Service and RTI Cloud Discovery Service,
you can use the command-line option -ignoreXsdValidation
to disable XSD
validation, but this is not recommended.
2.1.5.3. Use new XML tag names <participant_qos>, <filter>, and <parameter_list>¶
Some XML tags were renamed to make the schema compliant with the latest DDS-XML specification:
Table 2.2 XML Tag Name Changes¶ Pre-6.1.0 tag
6.1.0 tag
<participant_qos>
<domain_participant_qos>
<filter>
<content_filter>
<parameter_list>
in<filter>
<expression_parameters>
in<content_filter>
<value>
in<parameter_list>
<element>
in<expression_parameters>
The old tags are still accepted by the Connext XML parser and the XSD schema to maintain backward compatibility. However, you should transition to the new tags.
This issue also affects the Micro Application Generator (MAG).
2.1.5.4. XML fields of type duration have unset tags default to 0 with a warning log message¶
The duration type tag has two subfields, <sec>
and <nanosec>
. Some QoS policies
that use these fields, such as the DEADLINE QoS Policy, set the default duration to
INFINITE. In previous releases, if you had set just one of these fields
(<sec>
, but not <nanosec>
, or vice-versa), the resulting duration value was
still INFINITE. This was a problem that is now resolved in 6.1.0.
In 6.1.0, if you set only one of these fields (<sec>
or <nanosec>
) in the XML
file, the other value defaults to 0. (If you set neither one of them, the default
duration for that policy will be used.) A warning message will also be logged by the
parser specifying the parent tag, the missing subfield, and the line number.
This change is only a migration issue if you are using XML inheritance in your QoS XML file, expecting the missing value to be inherited from an ancestor. (Setting only one of two duration fields and relying on partial inheritance isn’t best practice, however.)
This issue also affects the Micro Application Generator (MAG).
2.1.5.5. Instance replacement changes affect XML files in Micro Application Generator (MAG)¶
This issue only affects XML files used by Micro Application Generator (MAG) for use
in Connext DDS Micro. The issue affects only MAG because the <instance_replacement>
tag was added in 6.0.1 for MAG, but it is new in 6.1.0 for the Connext DDS
Core Libraries.
(See Configure how instances will be replaced …, in What’s New in 6.1.0.)
As a result of this new functionality in the Core Libraries, the type used by
<instance_replacement>
in MAG has been changed from a single type to a complex type.
Because of this change, XML files used by MAG in previous releases won’t work out of
the box in 6.1.0. For example, the following XML worked in 6.0.1 in MAG, but will not
in 6.1.0:
<datareader_qos>
<reader_resource_limits>
<instance_replacement>OLDEST_INSTANCE_REPLACEMENT</instance_replacement>
</reader_resource_limits>
</datareader_qos>
To work in 6.1.0, change the above XML to the following:
<datareader_qos>
<reader_resource_limits>
<instance_replacement>
<alive_instance_removal>ANY_INSTANCE_REMOVAL</alive_instance_removal>
<disposed_instance_removal>ANY_INSTANCE_REMOVAL</disposed_instance_removal>
<no_writers_instance_removal>ANY_INSTANCE_REMOVAL</no_writers_instance_removal>
</instance_replacement>
</reader_resource_limits>
</datareader_qos>