layout | title | permalink | abstract | published | author | date_written | last_modified | categories |
---|---|---|---|---|---|---|---|---|
default |
IDL - Interface Definition and Language Mapping |
articles/idl_interface_definition.html |
This describes defining interfaces using a subset of the [Interface Definition Language](https://www.omg.org/spec/IDL/) (IDL). |
true |
[Dirk Thomas](https://github.com/dirk-thomas) |
2019-03 |
2020-07 |
Interfaces |
{:toc}
{{ page.title }}
Authors: {{ page.author }}
Date Written: {{ page.date_written }}
Last Modified: {% if page.last_modified %}{{ page.last_modified }}{% else %}{{ page.date_written }}{% endif %}
Scope
This article identifies a subset of the Interface Definition Language (IDL) that can be used to describe interfaces between components. Further it describes how the interfaces are used to generate code in C, C++ and Python.
Supported subset of IDL
ROS 2 supports a subset of the OMG IDL 4.2 specification. Whatever is not listed below is probably not supported at the moment (e.g. enums).
Lexical Conventions
7.2.2 Comments
Both line comments (//
) as well as block comments (/* ... */
) are being supported.
7.2.3 Identifiers
An identifier must start with an is an ASCII alphabetic characteran followed by any number of ASCII alphabetic, digit and underscore (_
) characters.
7.2.6 Literals
All of the following literals are supported:
- Integer
- Character
- String
- Floating-point
- Fixed-point
Preprocessing
At the moment there is no preprocessing happening when reading the `.idl files.
Building Blocks
7.4.6.4.1.4 Imports
Imports must be used to reference other .idl
file which declare data types
used in this .idl
file.
7.4.1.4.2 Modules
Each module must contain at least one definition and they can be nested.
For ROS interfaces the first module level commonly represents the package name,
the second module level distinguishes the type of the interface (msg
, srv
,
action
).
7.4.1.4.3 Constants
7.4.1.4.4.4.1 Structures
A structure must contain at least one member.
Basic Types
7.4.1.4.4.2.1 Integer Types
IDL type | Value range |
---|---|
short | -2^15 ... 2^15 - 1 |
unsigned short | 0 ... 2^16 - 1 |
long | -2^31 ... 2^31 - 1 |
unsigned long | 0 ... 2^32 - 1 |
long long | -2^63 ... 2^63 - 1 |
unsigned long long | 0 ... 2^64 - 1 |
7.4.1.4.4.2.2 Floating-Point Types
IDL type | Format |
---|---|
float | IEEE single-precision floating point number |
double | IEEE double-precision floating point number |
long double | IEEE double-extended floating-point number |
7.4.1.4.4.2.3 Char Type
IDL type | Value range |
---|---|
char | A 8-bit single-byte character with a numerical value between 0 and 255 (see 7.2.6.2.1) |
The type can store a single-byte character from any byte-oriented code set, or when used in an array, encode a multi-byte character from a multi-byte code set.
7.4.1.4.4.2.4 Wide Char Type
IDL type | Value range |
---|---|
wchar | A 16-bit wide character |
While the IDL spec only defines the size of wchar as implementation-dependent the DDS-XTypes specification 1.2 defines it with 16-bit.
7.4.1.4.4.2.5 Boolean Type
IDL type | Value range |
---|---|
boolean | One of the values TRUE and FALSE |
7.4.1.4.4.2.6 Octet Types
IDL type | Value range |
---|---|
octet | opaque 8-bit |
7.4.13.4.4 8-bits Integers
IDL type | Value range |
---|---|
int8 | -2^7 ... 2^7 - 1 |
uint8 | 0 ... 2^8 - 1 |
7.4.13.4.5 Explicitly-named Integer Types
IDL type | Equivalent IDL type |
---|---|
int16 | short |
uint16 | unsigned short |
int32 | long |
uint32 | unsigned long |
int64 | long long |
uint64 | unsigned long long |
Template Types
7.4.1.4.4.3.1 Sequences
IDL type | Value range |
---|---|
sequence<type_spec> | sequence of items of the specific type_spec |
the sequence is unbounded and no maximum size is specified | |
sequence<type_spec, N> | sequence of of up to N items of the specified type_spec |
the sequence is bounded and contain between 0 and N items |
7.4.1.4.4.3.2 Strings
IDL type | Value range |
---|---|
string | sequence of char except null |
7.4.1.4.4.3.3 Wstrings
IDL type | Value range |
---|---|
wstring | sequence of wchar except null |
Constructed Types
7.4.1.4.4.4.1 Structures
A structure is a grouping of at least one member.
7.4.1.4.4.4.3 Enumerations
An enumerated type consist of an ordered list of enumerators.
7.4.1.4.4.5 Arrays
A multidimensional, fixed-size array is defined by the type of each item and the explicit sizes for each dimension. For now only a one-dimensional, fixed-size array is supported though.
Annotations
The syntax for arbitrary annotations is supported. How each annotation type is being handled depends on the code generation described below.
Code Generation
Constraint Checking
Generated code for messages is only guaranteed to enforce constraints when a message is published. For example, there might not be an error when a field constrained to be a fixed size array is assigned an array with the wrong size. This could be inconsistent across client library implementations depending on language features and performance cost. In the future any client library may add additional constraint checking when a field is set or modified. Users of generated message code should assume constraints could be enforced at any time to be compatible with such a change.
Type Mapping
The next table defines how IDL types are mapped to the following programming languages:
- C11 (or higher)
- C++11 (or higher)
- Python 3 (or higher)
IDL type | C type | C++ type | Python type |
---|---|---|---|
float | float | float | float |
double | double | double | float |
long double | long double | long double2 | float |
char | unsigned char | unsigned char | str with length 1 |
wchar | char16_t | char16_t | str with length 1 |
boolean | _Bool | bool | bool |
octet | unsigned char | std::byte1 | bytes with length 1 |
int8 | int8_t | int8_t | int |
uint8 | uint8_t | uint8_t | int |
int16 | int16_t | int16_t | int |
uint16 | uint16_t | uint16_t | int |
int32 | int32_t | int32_t | int |
uint32 | uint32_t | uint32_t | int |
int64 | int64_t | int64_t | int |
uint64 | uint64_t | uint64_t | int |
- If std::byte is not available then unsigned char is used instead.
- Users should research the support for
long double
with their choice of middleware and platform. For example, it is only 64 bits when using Visual Studio.
The next table defines how IDL templated and constructed types are mapped to the programming languages (unless specified otherwise below).
When specified T
is either one of the types above or an IDL struct.
N
is the upper limit of a bounded type.
IDL type | C type | C++ type | Python type |
---|---|---|---|
T[N] | T[N] | std::array<T, N> | list |
sequence<T> | struct {size_t, T * } | std::vector<T> | list |
sequence<T, N> | struct {size_t, T * }, size_t N | std::vector<T> | list |
string | char * | std::string | str |
string<N> | char * | std::string | str |
wstring | char16_t * | std::u16string | str |
wstring<N> | char16_t * | std::u16string | str |
These array and sequence types have special mappings. If a cell is blank then the default mapping is used.
IDL type | C type | C++ type | Python type | ||
---|---|---|---|---|---|
T[N] | for numeric types T: float, double, int8, uint8, int16, uint16, int32, uint32, int64, uint64 |
- | - | numpy.ndarray( shape=(N, ), dtype=numpy.DT) |
where DT is determined by T: float -> float32, double -> float64, intX -> intX, uintX -> uintX |
sequence<T> sequence<T, N> |
for numeric types T: float, double, int8, uint8, int16, uint16, int32, uint32, int64, uint64 |
- | - | array.array(typecode=TC) | where TC is determined by T: float -> f, double -> d, int8 -> b, uint8 -> B, int16 -> h, uint16 -> H, int32 -> l, uint32 -> L, int64 -> q, uint64 -> Q |
octet[N] | - | - | bytes | ||
sequence<octet> | - | - | bytes | ||
sequence<octet, N> | - | - | bytes |
Standardized Annotations
8.3.2.1 @key Annotation
While the key annotation doesn't affect the generated ROS data types directly it is being passed through to the (DDS) vendor specific code generators.
8.3.3.1 @default Annotation
The default value is being used to initialize struct members.
8.3.5.1 @verbatim Annotation
When the value comment
is passed as the language
parameter the text parameter is used as the docblock for the annotated element across all supported programming languages.