# 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, ENU, 0, f] [offset] [max] [ADR, BMK, 0, f] [offset] [bits-high] [bits-low] [ADR, STR, 0, f] [offset] [ADR, BST, 0, f] [offset] [max-size]

      [ADR, SEQ, nBY, f] [offset] [ADR, SEQ, BLN, f] [offset] [ADR, SEQ, ENU, f] [offset] [max] [ADR, SEQ, BMK, f] [offset] [bits-high] [bits-low] [ADR, SEQ, STR, f] [offset] [ADR, SEQ, BST, 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, ENU, f] [offset] [sbound] [max] [ADR, BSQ, BMK, f] [offset] [sbound] [bits-high] [bits-low] [ADR, BSQ, STR, f] [offset] [sbound] [ADR, BSQ, BST, 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, ENU, f] [offset] [alen] [max] [ADR, ARR, BMK, f] [offset] [alen] [bits-high] [bits-low] [ADR, ARR, STR, f] [offset] [alen] [ADR, ARR, BST, 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

  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

  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

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)

    at arbitrary deep nesting the topic type contains at least one union.

  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_FIXED_KEY_MAX_SIZE (16)

    Max size of fixed key.