Serialization

group serialization

Opcodes for (de)serialization of types generated by idlc. Isolated in a separate header to share with idlc without the need to pull in the entire Eclipse Cyclone DDS C language binding.

One opcode is a uint32 and depending on which code it is can contain several uint32 arguments.

Defines

DDS_OP_MASK 0xff000000

Mask for the OP.

DDS_OP_TYPE_FLAGS_MASK 0x00800000

Mask for the OP type flags.

DDS_OP_TYPE_MASK 0x007f0000

Mask for the OP type.

DDS_OP_SUBTYPE_MASK 0x0000ff00

Mask for the OP subtype.

DDS_OP_JMP_MASK 0x0000ffff

Mask for the OP jump.

DDS_OP_FLAGS_MASK 0x000000ff

Mask for the OP flags.

DDS_JEQ_TYPE_FLAGS_MASK 0x00800000

Mask for the JEQ type flags.

DDS_JEQ_TYPE_MASK 0x007f0000

Mask for the JEQ type.

DDS_PLM_FLAGS_MASK 0x00ff0000

Mask for the PLM flags.

DDS_KOF_OFFSET_MASK 0x0000ffff

Mask for the KOF offset.

DDS_OP(o) ((enum dds_stream_opcode) ((o) & DDS_OP_MASK))

Extract the DDS OP from a uint32 as a dds_stream_opcode.

DDS_OP_TYPE(o) ((enum dds_stream_typecode) (((o) & DDS_OP_TYPE_MASK) >> 16))

Extract the DDS OP_TYPE from a uint32 as a dds_stream_typecode.

DDS_OP_TYPE_FLAGS(o) ((o) & DDS_OP_TYPE_FLAGS_MASK)

Extract the DDS OP_TYPE_FLAGS from a uint32 DOC_TODO: possible values?

DDS_OP_SUBTYPE(o) ((enum dds_stream_typecode) (((o) & DDS_OP_SUBTYPE_MASK) >> 8))

Extract the DDS OP_SUBTYPE from a uint32 as a dds_stream_typecode Used for collections, the OP_TYPE is array/sequence.

DDS_OP_FLAGS(o) ((o) & DDS_OP_FLAGS_MASK)

Extract the DDS OP_FLAGS from a uint32 DOC_TODO: possible values?

DDS_OP_ADR_JSR(o) ((int16_t) ((o) & DDS_OP_JMP_MASK))

Extract the ADR JSR from a uint32 DOC_TODO: meaning?

DDS_OP_ADR_PLM(o) ((int16_t) ((o) & DDS_OP_JMP_MASK))

Extract the ADR PLM from a uint32 DOC_TODO: meaning?

DDS_OP_LENGTH(o) ((uint16_t) ((o) & DDS_OP_JMP_MASK))

Extract the LENGTH from a uint32 DOC_TODO: meaning?

DDS_OP_JUMP(o) ((int16_t) ((o) & DDS_OP_JMP_MASK))

Extract the JUMP from a uint32 DOC_TODO: meaning?

DDS_OP_ADR_JMP(o) ((o) >> 16)

Extract the ADR_JMP from a uint32 DOC_TODO: meaning?

DDS_JEQ_TYPE(o) ((enum dds_stream_typecode) (((o) & DDS_JEQ_TYPE_MASK) >> 16))

Extract the JEQ_TYPE from a uint32 as a dds_stream_typecode DOC_TODO: meaning?

DDS_JEQ_TYPE_FLAGS(o) ((o) & DDS_JEQ_TYPE_FLAGS_MASK)

Extract the JEQ_TYPE_FLAGS from a uint32 DOC_TODO: meaning?

DDS_PLM_FLAGS(o) ((enum dds_stream_typecode) (((o) & DDS_PLM_FLAGS_MASK) >> 16))

Extract the PLM_FLAGS from a uint32 as a dds_stream_typecode DOC_TODO: meaning?

DDS_OP_FLAG_EXT (1u << 23)

This flag indicates that the type has external data (i.e. a mapped to a pointer type), which can be the case because of (1) the @external annotation in idl or (2) the @optional annotation (optional fields are also mapped to pointer types as described in the XTypes spec). This flag is stored in the most-significant bit of the ‘type’ part of the serializer instruction.

DDS_OP_FLAG_KEY (1u << 0)

mark field as key applicable to {1,2,4,8}BY, STR, BST, ARR-of-{1,2,4,8}BY. Note that when defining keys in nested types, the key flag should be set on both the field(s) in the subtype and on the enclosing STU/EXT field.

DDS_OP_FLAG_DEF (1u << 1)

For a union:

1. the discriminator may be a key field;

   1. there may be a default value;

   2. and the discriminator can be an integral type (or enumerated - here treated as equivalent). What it can’t be is a floating-point type. So DEF and FP need never be set at the same time. There are only a few flag bits, so saving one is not such a bad idea.

union has a default case (for DDS_OP_ADR | DDS_OP_TYPE_UNI)

DDS_OP_FLAG_FP (1u << 1)

floating-point, applicable to {4,8}BY and arrays, sequences of them

DDS_OP_FLAG_SGN (1u << 2)

signed, applicable to {1,2,4,8}BY and arrays, sequences of them

DDS_OP_FLAG_MU (1u << 3)

must-understand flag, as defined by the XTypes spec.

DDS_OP_FLAG_BASE (1u << 4)

jump to base type, used with PLM in mutable types and for the TYPE_EXT ‘parent’ member in final and appendable types

DDS_OP_FLAG_OPT (1u << 5)

optional flag, used with struct members. For non-string types, an optional member also gets the FLAG_EXT, see above.

DDS_OP_FLAG_SZ_SHIFT (6)

Enum and bitmask storage size (shift amount)

DDS_OP_FLAG_SZ_MASK (3u << DDS_OP_FLAG_SZ_SHIFT)

Enum and bitmask storage size.

1. 00 = 1 byte,

   1. 01 = 2 bytes,

   2. 10 = 4 bytes,

   3. 11 = 8 bytes (bitmask only)

DDS_OP_FLAGS_SZ(f) (1u << (((f) & DDS_OP_FLAG_SZ_MASK) >> DDS_OP_FLAG_SZ_SHIFT))

Extract the Enum and Bitmask storage size from flags.

DDS_OP_TYPE_SZ(o) DDS_OP_FLAGS_SZ(DDS_OP_FLAGS(o))

Extract the Enum and Bitmask storage size from an uint32.

Enums

enum dds_stream_opcode

Topic encoding instruction types.

Values:

enumerator DDS_OP_RTS

return from subroutine, exits top-level [RTS, 0, 0, 0]

enumerator DDS_OP_ADR

data field [ADR, nBY, 0, f] [offset] [ADR, BLN, 0, f] [offset] [ADR, WCHAR, 0, f] [offset] [ADR, ENU, 0, f] [offset] [max] [ADR, BMK, 0, f] [offset] [bits-high] [bits-low] [ADR, STR, 0, f] [offset] [ADR, WSTR, 0, f] [offset] [ADR, BST, 0, f] [offset] [max-size] [ADR, BWSTR, 0, f] [offset] [max-size]

[ADR, SEQ, nBY, f] [offset] [ADR, SEQ, BLN, f] [offset] [ADR, SEQ, WCHAR, f] [offset] [ADR, SEQ, ENU, f] [offset] [max] [ADR, SEQ, BMK, f] [offset] [bits-high] [bits-low] [ADR, SEQ, STR, f] [offset] [ADR, SEQ, WSTR, f] [offset] [ADR, SEQ, BST, f] [offset] [max-size] [ADR, SEQ, BWSTR, f] [offset] [max-size] [ADR, SEQ, s, f] [offset] [elem-size] [next-insn, elem-insn] where s = {SEQ,ARR,UNI,STU,BSQ} [ADR, SEQ, EXT, f] *** not supported

[ADR, BSQ, nBY, f] [offset] [sbound] [ADR, BSQ, BLN, f] [offset] [sbound] [ADR, BSQ, WCHAR, f] [offset] [sbound] [ADR, BSQ, ENU, f] [offset] [sbound] [max] [ADR, BSQ, BMK, f] [offset] [sbound] [bits-high] [bits-low] [ADR, BSQ, STR, f] [offset] [sbound] [ADR, BSQ, WSTR, f] [offset] [sbound] [ADR, BSQ, BST, f] [offset] [sbound] [max-size] [ADR, BSQ, BWSTR, f] [offset] [sbound] [max-size] [ADR, BSQ, s, f] [offset] [sbound] [elem-size] [next-insn, elem-insn] where s = {SEQ,ARR,UNI,STU,BSQ} [ADR, BSQ, EXT, f] *** not supported

[ADR, ARR, nBY, f] [offset] [alen] [ADR, ARR, BLN, f] [offset] [alen] [ADR, ARR, WCHAR, f] [offset] [alen] [ADR, ARR, ENU, f] [offset] [alen] [max] [ADR, ARR, BMK, f] [offset] [alen] [bits-high] [bits-low] [ADR, ARR, STR, f] [offset] [alen] [ADR, ARR, WSTR, f] [offset] [alen] [ADR, ARR, BST, f] [offset] [alen] [0] [max-size] [ADR, ARR, BWSTR, f] [offset] [alen] [0] [max-size] [ADR, ARR, s, f] [offset] [alen] [next-insn, elem-insn] [elem-size] where s = {SEQ,ARR,UNI,STU,BSQ} [ADR, ARR, EXT, f] *** not supported

[ADR, UNI, d, z] [offset] [alen] [next-insn, cases] [ADR, UNI, ENU, z] [offset] [alen] [next-insn, cases] [max] [ADR, UNI, EXT, f] *** not supported where d = discriminant type of {1BY,2BY,4BY,BLN} z = default present/not present (DDS_OP_FLAG_DEF) offset = discriminant offset max = max enum value followed by alen case labels: in JEQ format

[ADR, e | EXT, 0, f] [offset] [next-insn, elem-insn] [elem-size iff “external” flag e is set, or flag f has DDS_OP_FLAG_OPT] [ADR, STU, 0, f] *** not supported where s = subtype e = external: stored as external data (pointer) (DDS_OP_FLAG_EXT) f = flags:

• key/not key (DDS_OP_FLAG_KEY)

• base type member, used with EXT type (DDS_OP_FLAG_BASE)

• optional (DDS_OP_FLAG_OPT)

• must-understand (DDS_OP_FLAG_MU)

• storage size, only for ENU and BMK (n << DDS_OP_FLAG_SZ_SHIFT) [offset] = field offset from start of element in memory [elem-size] = element size in memory (elem-size is only included in case ‘external’ flag is set) [max-size] = string bound + 1 [max] = max enum value [bits-..] = identified bits in the bitmask, split into high and low 32 bits [alen] = array length, number of cases [sbound] = bounded sequence maximum number of elements [next-insn] = (unsigned 16 bits) offset to instruction for next field, from start of insn [elem-insn] = (unsigned 16 bits) offset to first instruction for element, from start of insn [cases] = (unsigned 16 bits) offset to first case label, from start of insn

enumerator DDS_OP_JSR

jump-to-subroutine (e.g. used for recursive types and appendable unions) [JSR, 0, e] where e = (signed 16 bits) offset to first instruction in subroutine, from start of insn instruction sequence must end in RTS, execution resumes at instruction following JSR

enumerator DDS_OP_JEQ

jump-if-equal, used for union cases: [JEQ, nBY, 0] [disc] [offset] [JEQ, BLN, 0] [disc] [offset] [JEQ, STR, 0] [disc] [offset] [JEQ, s, i] [disc] [offset] [JEQ4, e | nBY, 0] [disc] [offset] 0 [JEQ4, e | STR, 0] [disc] [offset] 0 [JEQ4, e | ENU, f] [disc] [offset] [max] [JEQ4, EXT, 0] *** not supported, use STU/UNI for external defined types [JEQ4, e | s, i] [disc] [offset] [elem-size iff “external” flag e is set, else 0] where e = external: stored as external data (pointer) (DDS_OP_FLAG_EXT) s = subtype other than {nBY,STR} for JEQ and {nBY,STR,ENU,EXT} for JEQ4 (note that BMK cannot be inline, because it needs 2 additional instructions for the bits that are identified in the bitmask type) i = (unsigned 16 bits) offset to first instruction for case, from start of insn instruction sequence must end in RTS, at which point executes continues at the next field’s instruction as specified by the union f = size flags for ENU instruction

Note that the JEQ instruction is deprecated and replaced by the JEQ4 instruction. The IDL compiler only generates JEQ4 for union cases, the JEQ instruction is included here for backwards compatibility (topic descriptors generated with a previous version of IDLC)

enumerator DDS_OP_DLC

XCDR2 delimited CDR (inserts DHEADER before type) [DLC, 0, 0]

enumerator DDS_OP_PLC

XCDR2 parameter list CDR (inserts DHEADER before type and EMHEADER before each member) [PLC, 0, 0] followed by a list of JEQ instructions

enumerator DDS_OP_PLM

[PLM, f, elem-insn] [member id] for members of aggregated mutable types (pl-cdr): where f = flags:

• jump to base type (DDS_OP_FLAG_BASE) [elem-insn] = (unsigned 16 bits) offset to instruction for element, from start of insn when FLAG_BASE is set, this is the offset of the PLM list of the base type [member id] = id for this member (0 in case FLAG_BASE is set)

enumerator DDS_OP_KOF

Key offset list [KOF, 0, n] [offset-1] … [offset-n] where n = number of key offsets in following ops offset = Offset of the key field relative to the previous offset, repeated n times when key is in a nested struct. In case of inheritance of mutable structs, a single offset of the key member relative to the first op of the top-level type (index 0).

enumerator DDS_OP_JEQ4

see comment for JEQ/JEQ4 above

enum dds_stream_typecode

datatypes as recognized by serialization VM.

Values:

enumerator DDS_OP_VAL_1BY

one byte simple type (char, octet)

enumerator DDS_OP_VAL_2BY

two byte simple type ((unsigned) short)

enumerator DDS_OP_VAL_4BY

four byte simple type ((unsigned) long, float)

enumerator DDS_OP_VAL_8BY

eight byte simple type ((unsigned) long long, double)

enumerator DDS_OP_VAL_STR

string

enumerator DDS_OP_VAL_BST

bounded string

enumerator DDS_OP_VAL_SEQ

sequence

enumerator DDS_OP_VAL_ARR

array

enumerator DDS_OP_VAL_UNI

union

enumerator DDS_OP_VAL_STU

struct

enumerator DDS_OP_VAL_BSQ

bounded sequence

enumerator DDS_OP_VAL_ENU

enumerated value (long)

enumerator DDS_OP_VAL_EXT

field with external definition

enumerator DDS_OP_VAL_BLN

boolean

enumerator DDS_OP_VAL_BMK

bitmask

enumerator DDS_OP_VAL_WSTR

wstring (UTF-16)

enumerator DDS_OP_VAL_BWSTR

bounded wstring (UTF-16)

enumerator DDS_OP_VAL_WCHAR

wchar: UTF-16, no surrogates allowed

enum dds_stream_typecode_primary

primary type code for DDS_OP_ADR, DDS_OP_JEQ Convinience pre-bitshifted values.

Values:

enumerator DDS_OP_TYPE_1BY

one byte simple type (char, octet)

enumerator DDS_OP_TYPE_2BY

two byte simple type ((unsigned) short)

enumerator DDS_OP_TYPE_4BY

four byte simple type ((unsigned) long, float)

enumerator DDS_OP_TYPE_8BY

eight byte simple type ((unsigned) long long, double)

enumerator DDS_OP_TYPE_STR

string

enumerator DDS_OP_TYPE_BST

bounded string

enumerator DDS_OP_TYPE_SEQ

sequence

enumerator DDS_OP_TYPE_ARR

array

enumerator DDS_OP_TYPE_UNI

union

enumerator DDS_OP_TYPE_STU

struct

enumerator DDS_OP_TYPE_BSQ

bounded sequence

enumerator DDS_OP_TYPE_ENU

enumerated value (long)

enumerator DDS_OP_TYPE_EXT

field with external definition

enumerator DDS_OP_TYPE_BLN

boolean

enumerator DDS_OP_TYPE_BMK

bitmask

enumerator DDS_OP_TYPE_WSTR

wstring (UTF-16)

enumerator DDS_OP_TYPE_BWSTR

bounded wstring (UTF-16)

enumerator DDS_OP_TYPE_WCHAR

wchar: UTF-16, no surrogates allowed

enum dds_stream_typecode_subtype

sub-type code

• encodes element type for DDS_OP_TYPE_{SEQ,ARR},

• discriminant type for DDS_OP_TYPE_UNI Convinience pre-bitshifted values.

Values:

enumerator DDS_OP_SUBTYPE_1BY

one byte simple type (char, octet)

enumerator DDS_OP_SUBTYPE_2BY

two byte simple type ((unsigned) short)

enumerator DDS_OP_SUBTYPE_4BY

four byte simple type ((unsigned) long, float)

enumerator DDS_OP_SUBTYPE_8BY

eight byte simple type ((unsigned) long long, double)

enumerator DDS_OP_SUBTYPE_STR

string

enumerator DDS_OP_SUBTYPE_BST

bounded string

enumerator DDS_OP_SUBTYPE_SEQ

sequence

enumerator DDS_OP_SUBTYPE_ARR

array

enumerator DDS_OP_SUBTYPE_UNI

union

enumerator DDS_OP_SUBTYPE_STU

struct

enumerator DDS_OP_SUBTYPE_BSQ

bounded sequence

enumerator DDS_OP_SUBTYPE_ENU

enumerated value (long)

enumerator DDS_OP_SUBTYPE_BLN

boolean

enumerator DDS_OP_SUBTYPE_BMK

bitmask

enumerator DDS_OP_SUBTYPE_WSTR

wstring

enumerator DDS_OP_SUBTYPE_BWSTR

bounded wstring

enumerator DDS_OP_SUBTYPE_WCHAR

wchar: UTF-16, no surrogates allowed

group topic_flags

There are several flags that can be added to dds_topic_descriptor_t by the IDL compiler.

Defines

DDS_TOPIC_NO_OPTIMIZE (1u << 0)

Don’t optimize the opcodes to quick memcpy’s. If a topic includes only plain types and directly nested structs, it can be that a simple copy+optional byteswap can produce the right C memory layout straight from CDR. If this flag is added it means that there is pointer ‘magic’ involved in decoding the type and no shortcuts should be taken.

Deprecated:

Optimizability is determined runtime when creating the sertype_default for the type, this flag is not used.

DDS_TOPIC_FIXED_KEY (1u << 1)

The XCDRV1 serialized key fits in 16 bytes. If statically determined that a key always fits in 16 bytes the spec specifies that the key of a sample is the resulting CDR. If it is longer we must use MD5 to hash the resultant key CDR.

DDS_TOPIC_CONTAINS_UNION (1u << 2)

ignored

Deprecated:

reserved for backward compatibility

DDS_TOPIC_FIXED_SIZE (1u << 4)

The size in memory of a sample of this topic type is fully fixed.

DDS_TOPIC_FIXED_KEY_XCDR2 (1u << 5)

The XCDRV2 serialized key fits in 16 bytes. If statically determined that a key always fits in 16 bytes the spec specifies that the key of a sample is the resulting CDR. If it is longer we must use MD5 to hash the resultant key CDR.

This is separate from the XCDRV1 version because it can differ due to the change in alignment of 8byte types.

DDS_TOPIC_XTYPES_METADATA (1u << 6)

Set if XTypes meta-data is present for this topic.

DDS_TOPIC_RESTRICT_DATA_REPRESENTATION (1u << 7)

Set if data representation restrictions for the top-level type are present in the topic descriptor.

DDS_TOPIC_KEY_MUTABLE (1u << 8)

Set if any of the key fields of a type is in a mutable aggregated type.

DDS_TOPIC_KEY_APPENDABLE (1u << 9)

Set if any of the key fields of a type is in an appendable aggregated type.

DDS_TOPIC_FIXED_KEY_XCDR2_KEYHASH (1u << 10)

The XCDRV2 serialized key with field in member-id order fits in 16 bytes. If statically determined that a serialized key that is used to get the keyhash always fits in 16 bytes, the spec specifies that the keyhash of a sample is the resulting CDR. If it is longer we must use MD5 to hash the resultant key CDR.

The XCDRV1 key-hash is calculated from the serialized key with the fields in definition order, so DDS_TOPIC_FIXED_KEY can also be used for key-hash for XCDR1.

DDS_FIXED_KEY_MAX_SIZE (16)

Max size of fixed key.