DDL Definition File Format

Table of Contents

• Description of General Datatypes in this specification
• header
• units
  • baseunits
  • prefixes
  • units
  • Calculation of new unit
• datatypes
• enums
• constants
• structs
  • Alignment of structs and in structs
  • Why should I use anything else but an alignment of 1?
• dynamic arrays
• Fastest way to use dynamic arrays:
• When the dynamic data is not the last element the bytepos of the following elements must be -1:
• Dynamic array of complex data:
• streammetatypes
• predefined elements

Remarks

This package is deprecated and is only there for binary compatibility reason. Use the DDL Library instead and have a look at the ADTF Media Description SDK and DDL and ADTF 3.

Which DDL Definition File(s) are used in ADTF can be specified in ADTF Configuration Editor or ADTF Config Tool within the Media Description Service Plugin. If more than one DDL Definition File is provided, the contained information will be merged.

The DDL were released with several versions. This table will show the the supported DDL versions of different ADTF releases.

Warning

Keep in mind, that the DDL language version 1.0 is not supported within ADTF.

The currently valid and used version is DDL 4.0.

ADTF Version	DDL Version supported
2.4.x	1.0+
2.5.x	1.0+
2.6.x	1.0+
2.7.x	1.0+ and 1.02
2.8.x	1.0+, 1.02, and 2.0
2.9.x	1.0+, 1.02, and 2.0
2.10.x and newer	1.0+, 1.02, 2.0, and 3.0
3.0.x and newer	1.0+, 1.02, 2.0, 3.0 and 4.0

Changes to definitions between the language versions are explicitly explained in the tables below.

Description of General Datatypes in this specification

There are several types that are used in attributes and as tag data in the DDL. The following table lists the types with a description of the values and/or their formatting.

Type	Allowed values
Char	Single character of [a-z][A-Z][0-9] _.-+/
String	Characters of [a-z][A-Z][0-9] _.-+/
Text	All visible ASCII characters
UInt	Unsigned integer values
Int	signed integer values
Float	signed float values
Date	Allowed formats: yyyymmdd, dd-mm-yyyy, yyyy-mm-dd or dd.mm.yyyy
Class	any name value of another DDL element
Enum	A predefined value from the description of the attribute

This file contains the following sections:

• header
• units
• datatypes
• enums
• structs
• streammetatypes

ADTF provides several predefined baseunits, prefixes, datatypes and enums. For further information see predefined elements.

header

The header section contains meta information about the document and version information. Example:

<header>
    <language_version>4.0</language_version>
    <author>AUDI Electronics Venture GmbH</author>
    <date_creation>20100407</date_creation>
    <date_change />
    <description>ADTF Common Description File</description>
</header>

Tag	Type	Description
language_version	Float	Version number of the file
author	String	Author
date_creation	Date	Creation date
date_change	Date	Last modification date
description	Text	Short description

All previously mentioned header tags are mandatory.

Additional information can be added by using the ext_declaration tag. Example:

<header>
    ...
    <ext_declaration key="AnyKey" value="Any value for this key"/>
</header> 

Attribute	Type	Description
key	String	Name of the additional information
Value	Text	Value of the additional information

units

The definition of units will be divided in SI-base units and own units. The SI-based units are the following ones:

SI (see ISO 1000)	Metre	Gram	Second	Ampere	Candela	Kelvin	Mole
no SI, but needed for daily usage	Degree	Radiant	Unitless

Units are defined within the tags <units> and </units>. Example:

<units>
    <baseunit description="Fundamental unit for electric current" name="Ampere" symbol="A" />
    <baseunit description="Fundamental unit for luminous intensity" name="Candela" symbol="cd" />
    <baseunit description="Non-SI standard unit for angle" name="Degree" symbol="deg" /> 
    <baseunit description="Fundamental unit for thermodynamic temperature" name="Kelvin" symbol="K" />
    <baseunit description="Fundamental unit for mass" name="Kilogram" symbol="kg" />
    <baseunit description="Fundamental unit for length" name="Metre" symbol="m" />
    <baseunit description="Fundamental unit for amount of substance" name="Mole" symbol="mol" />
    <baseunit description="Non-SI standard unit for angle" name="Radiant" symbol="rad" />
    <baseunit description="Fundamental unit for time" name="Second" symbol="s" />
    <baseunit description="No SI, but needed for own unit definitions" name="Unitless" symbol="" />
 
    <prefixes name="atto" power="-18" symbol="a" />
    <prefixes name="centi" power="-2" symbol="c" />
    <prefixes name="deca" power="1" symbol="da" />
    <prefixes name="deci" power="-1" symbol="d" />
    <prefixes name="exa" power="18" symbol="E" />
    <prefixes name="femto" power="-15" symbol="f" />
    <prefixes name="giga" power="9" symbol="G" />
    <prefixes name="hecto" power="2" symbol="h" />
    <prefixes name="kilo" power="3" symbol="k" />
    <prefixes name="mega" power="6" symbol="M" />
    <prefixes name="micro" power="-6" symbol="u" />
    <prefixes name="milli" power="-3" symbol="m" />
    <prefixes name="nano" power="-9" symbol="n" />
    <prefixes name="peta" power="15" symbol="P" />
    <prefixes name="pico" power="-12" symbol="p" />
    <prefixes name="tera" power="12" symbol="T" />
    <prefixes name="yocto" power="-24" symbol="y" />
    <prefixes name="yotta" power="24" symbol="Y" />
    <prefixes name="zepto" power="-21" symbol="z" />
    <prefixes name="zetta" power="21" symbol="Z" />
</units>

baseunits

A concrete base unit definition will be specified by the tag <baseunit> and </baseunit>

The baseunit needs the following mandatory attributes:

Name	Value	Description
name	STRING	Name of the base unit e.g. metre
symbol	STRING	Symbol of the base unit e.g. m
description	TEXT	Description of the represented base unit

prefixes

Prefixes between 10 power(-24) and 10 power(24) are predefined. A prefix can be defined by the <prefixes> tag.

Every <prefixes> tag needs the following mandatory attributes:

Name	Value	Description
name	STRING	Name of the prefix
symbol	STRING	Represents a short symbol e.g. k
power	INT	Defines the power of the prefix

units

A self defined unit is specified within the <unit> and </unit> tag and needs the following mandatory attributes:

Name	Value	Description
name	STRING	Name of the new unit

The <unit> tags needs the following mandatory sub-tags:

Name	Value	Description
numerator	STRING containing pi/PI or afloating-point value	Numerator of the new unit related to the baseunits
denominator	STRING containing pi/PI or afloating-point value. The value '0' is not defined.	Denominator of the new unit related to the baseunits
offset	FLOAT	Offset to the baseunits

The new unit is able to use several base units. To represent this, it is possible to specify the related base units by the <refUnit> tag. This tag uses the following mandatory attributes:

Name	Value	Description
name	CLASS	The referenced unit
power	INT	Power of the new unit related to the base one
prefix	CLASS	Reference to the prefix to use

Calculation of new unit

The newly defined unit relates to the SI base units like this:

newUnit = offset + (numerator / denominator) * Product (prefix(n) * baseUnit(n) ^ power(n))

datatypes

This section describes the primitive data types which can be used within the struct elements. Example:

<datatypes>
    <datatype description="predefined ADTF tBool datatype"  size="8" name="tBool" />
    <datatype description="predefined ADTF tChar datatype"  size="8" name="tChar" />
    <datatype description="predefined ADTF tUInt8 datatype" size="8" name="tUInt8" />
    <datatype description="predefined ADTF tInt8 datatype"  size="8" name="tInt8" />
    ...     
</datatypes>

Name	Type	Required	Description
name	String	mandatory	Name of the primitive data type
size	UInt	mandatory	Number of bits (relevant for serialization)
description	String	optional	Description of the primitive data type
arraysize	UInt	optional	= 1 -> primitive presentation > 1 -> array with number of elements. This feature is not supported within DDL.
unit	Class	optional	Unit of the data type
min	String	optional	Minimum value of the data type
max	String	optional	Maximum value of the data type

The following predefined data types are provided with adtf.description:

Type	Description	Number of bits
tBool	Boolean	8 (C++ data type)
tBit	Bit	1
tChar	Character	8
tInt8	Signed integer	8
tUInt8	Unsigned integer	8
tInt16	Signed integer	16
tUInt16	Unsigned integer	16
tInt32	Signed integer	32
tUInt32	Unsigned integer	32
tInt64	Signed integer	64
tUInt64	Unsigned integer	64
tFloat32	IEEE Float	32
tFloat64	IEEE Float	64

enums

This section describes the enum type which can be used within the struct elements. Example:

<enums>
    <enum name="tValueDefinitions" type="tUInt32">
        <element name="ELEMENT_ONE" value="10"/>
        <element name="ELEMENT_TWO" value="20"/>
        <element name="ELEMENT_THREE" value="5"/>
    </enum>
    ...
</enums>
<struct alignment="1" name="tEnumData" version="1">
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="0" name="enumData" type="tValueDefinitions" />
</struct>

Enum Attributes

Name	Type	Required	Description
name	String	mandatory	Name of the enum
type	String	mandatory	Data type of the enum

Enum Element Attributes

Name	Type	Required	Description
name	String	mandatory	Name of the element
value	Type specific	mandatory	Value of the element

Remarks:

• An enum is also valid without enum elements.

constants

This section describes constants which are implemented using the enum type. Example:

<enums>
    <enum name="tConstants" type="tUInt32">
        <element name="CONSTANT_ONE" value="42"/>
        <element name="CONSTANT_TWO" value="10"/>
    </enum>
    ...     
</enums>
<struct alignment="1" name="tEnumData" version="1">
    <element alignment="1" arraysize="1" byteorder="LE" bytepos="0" name="enumData" type="tConstants" value="CONSTANT_ONE" />
</struct>

structs

The definition of structs allows to build complex data types. Example:

<struct alignment="4" name="tTest" version="1" ddlversion="4.0">
    <element name="bBool" type="tBool" arraysize="1">
        <serialized byteorder="LE" bytepos="0" bitpos="0" numbits="8"/>
        <deserialized alignment="1"/>
    </element>
    <element name="nInt8" type="tInt8" arraysize="1">
        <serialized byteorder="LE" bytepos="1" bitpos="0" numbits="8"/>
        <deserialized alignment="1"/>
    </element>
    <element name="nUInt32" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="2" bitpos="0" numbits="32"/>
        <deserialized alignment="4"/>
    </element>
    <element name="fFloat32" type="tFloat32" arraysize="1">
        <serialized byteorder="LE" bytepos="6" bitpos="0" numbits="32"/>
        <deserialized alignment="4"/>
    </element>
</struct>

The tag <struct> uses the following attributes:

Name	Type	Required	Description
name	String	mandatory	Description of the data type
version	UInt	mandatory	Version number of the specified data type
comment	Text	optional	Additional comments
alignment	Enum of 0/1/2/4/8/16/32/64 (defaut 1)	optional	Alignment value to get the whole packing of the complex data type which is important to get the calculated size of the structure (relevant for serialization)
ddlversion	String	optional	The version of the size calculation scheme, see alignment. If not specified the version from the containing definition will be used.

Remarks:

If the alignment is set to "0", the alignment will be set to the sum of the sizes of all types the struct contains!

The tag <serialized> uses the following attributes:

Name	Type	Required	Description	changes between DDL 3.0 and 4.0
type	Class	mandatory	Reference to an existing data type
name	String	mandatory	Name of the created element
bytepos	UInt	deprecated	Byte position of the data in the <serialized> representation of the containing struct. This is NOT relevant for the struct layout in memory (deserialized)! Started with '0' Elements following a dynamic array must have a byte pos of '-1'	From version 4.0 on this information is specified within the <serialized> tag.
bitpos	UInt	deprecated	Bit position of the data in the <serialized> representation of the containing struct. This is NOT relevant for the struct layout in memory (deserialized)! default = 0 (in the range of 0 to 7) (relevant for serialization)	From version 4.0 on this information is specified within the <serialized> tag.
numbits	UInt	deprecated	Specifies the amount of bits used in the <serialized> representation, if not set the size of the type will be used. e.g. tInt8 with numbits of 7 (numbits can only be used to non-arrays) This is NOT relevant for the struct layout in memory (deserialized)!	From version 4.0 on this information is specified within the <serialized> tag.
byteorder	Enum of LE/BE/Motorola/Intel	deprecated	Defines the byte order in the <serialized> representation.	From version 4.0 on this information is specified within the <serialized> tag.
alignment	Enum of 0/1/2/4/8/16/32/64	deprecated	Defines the alignment of the element in the <deserialized> representation. The alignment influences the size of the element. The size will always be a the lowest common multiple of the alignment and the size of the type of the element.	From version 4.0 on this information is specified within the <deserialized> tag.
description	String	optional	Description of the created data type
unit	Class	optional	Unit of the element
comment	Text	optional	Additional comments
arraysize	tUInt or String	mandatory	Defines the array size of the element. The default is arraysize="1". Starting with DDL 2.0 the name of a preceding struct element can be used to specify a dynamic array. arraysize="elementName" For a detailed explanation of dynamic arrays refer to dynamic arrays
value	Enum element	optional	Constant value for element
min	String	optional	Minimum value of the element
max	String	optional	Maximum value of the element
default	String	optional	Default value of the element
scale	String	optional	Scaling value of the element
offset	String	optional	Offset value of the element

The tag <serialized> uses the following attributes:

Name	Type	Required	Description
bytepos	UInt	mandatory	Byte position of the data in the <serialized> representation of the containing struct. This is NOT relevant for the struct layout in memory (deserialized)! Started with '0' Elements following a dynamic array must have a byte pos of '-1'
bitpos	UInt	optional	Bit position of the data in the <serialized> representation of the containing struct. This is NOT relevant for the struct layout in memory (deserialized)! default = 0 (in the range of 0 to 7) (relevant for serialization)
numbits	UInt	optional	Specifies the amount of bits used in the <serialized> representation, if not set the size of the type will be used. e.g. tInt8 with numbits of 7 (numbits can only be used to non-arrays) This is NOT relevant for the struct layout in memory (deserialized)!
byteorder	Enum of LE/BE/Motorola/Intel	mandatory	Defines the byte order in the <serialized> representation.

The tag <deserialized> uses the following attributes:

Name	Type	Required	Description
alignment	Enum of 0/1/2/4/8/16/32/64	deprecated	Defines the alignment of the element in the <deserialized> representation. The alignment influences the size of the element. The size will always be a the lowest common multiple of the alignment and the size of the type of the element.

Remarks:

• The number of structs defined in a DDL description file is not limited.
• If the name of another struct is used as type for an element, a hierarchical structure is created.
• The maximum depth of such hierarchical structures is limited by the value of the define ADTF_DDL_MAX_DESC_HIERARCHY.
• If the alignment is set to "0", the alignment will be set to the size of the elements type!

Alignment of structs and in structs

This section will explain the different meanings of alignment used in the DDL. Since alignment is only needed for deserialized representation, this section will only consider this kind of representation.

Inside a struct, every element has a explicit alignment value. This value influences, at what position the element will be placed inside the struct. The memory placement is initially determined by the order of the element tags inside the struct. After that the alignment takes effect. An element inside a struct will only be placed at memory positions that are multiples of the alignment value. The considered memory address is always relative to the beginning of the struct (memory position 0). As an example we assume having the following struct definition:

<struct alignment="4" name="tStruct" version="1">
    <element name="ui8Array" type="tUInt8" arraysize="5">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="ui32Value" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="5"/>
        <deserialized alignment="4"/>
    </element>
</struct>

In this case, ui8Array will be placed at address 0. Because of the order of the element tags, ui32Value has to be placed after ui8Array. The next memory position after ui8Array is 5. But since the element ui32Value has an alignment of 4 and therfore the memory address has to be a multiple of 4, ui32Value will be placed at address 8 since this is the first address to matches all requirements. The attibute bytepos is only valid for serialized representation.

The alignment of a struct does not affect the alignment of its elements. A struct's alignment only determines the positioning of this struct inside of arrays. Assuming we have the following struct:

<struct alignment="4" name="tInnerStruct" version="1">
    <element name="ui8Value1" type="tUInt8" arraysize="1">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="ui8Value2" type="tUInt8" arraysize="1">
        <serialized byteorder="LE" bytepos="1"/>
        <deserialized alignment="1"/>
    </element>
</struct>

Lets now assume we have another struct tOuterStruct, that contains an array element and the element's type is the struct tInnerStruct:

<struct alignment="1" name="tOuterStruct" version="1">
    <element name="aValue" type="tInnerStruct" arraysize="5">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
</struct>

Inside the array, the array element's positions are influenced by the alignment of the type (tInnerStruct). This means that the first array element is at position 0, in relation to the beginning of the array. The next free memory address would be 2, but since the alignment of the struct is 4, the memory address has to be a multiple of 4 and the second element of the array now is situated at memory address 4. The third will be at 8, the fourth at 12 and so on.

Why should I use anything else but an alignment of 1?

If for example you are planning to describe data with DDL that was originally defined as a struct in a header file, you should also define the alignment values inside your DDL file accordingly. If on the other hand you are shure, that the data you are using is always interpreted using DDL, there is no need to use an alignment other than 1.

dynamic arrays

Detailed explanation of the dynamic array functionality.
Dynamic arrays were introduced in DDL 2.0.

Attention

The use of dynamic arrays will cause a severe performance drop compared to static arrays.
It is therefore recommended to use static arrays whenever possible.
To minimize the performance impact of dynamic arrays the user should adhere to the following guidelines:

• Always place dynamic data the end of a structure or structure hirarchy so all static data precede the dynamic data.
• Use the struct element directly preceding the dynamic array for array size.
• Use dynamic arrays of primitive data types instead of complex data types.
• Prefer flat data over deeply structured data.
• Do not use nested dynamic arrays!
• Use alignment=1 for all elements.
• Use default values bitpos.
• Use a bytepos that matches the position in memory when alignment=1.

Attention

Dynamic Arrays cannot be used with the ADTF Signal Registry.

Fastest way to use dynamic arrays:

<struct alignment="1" name="tDynStruct" version="1">
    <element name="ui32SomeData" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="ui32DynArraySize" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="4"/>
        <deserialized alignment="1"/>
    </element>
    <element name="f64DynamicArray" type="tFloat64" arraysize="ui32DynArraySize">
        <serialized byteorder="LE" bytepos="8"/>
        <deserialized alignment="1"/>
    </element>
</struct>

When the dynamic data is not the last element the bytepos of the following elements must be -1:

<struct alignment="1" name="tDynStruct" version="1">
    <element name="ui32DynArraySize" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="f64DynamicArray" type="tFloat64" arraysize="ui32DynArraySize">
        <serialized byteorder="LE" bytepos="4"/>
        <deserialized alignment="1"/>
    </element>
    <element name="ui32SomeData" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="-1"/>
        <deserialized alignment="1"/>
    </element>
</struct>

Dynamic array of complex data:

<struct alignment="1" name="tVector" version="1">
    <element name="f64X" type="tFloat64" arraysize="1">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="f64Y" type="tFloat64" arraysize="1">
        <serialized byteorder="LE" bytepos="8"/>
        <deserialized alignment="1"/>
    </element>
    <element name="f64Z" type="tFloat64" arraysize="1">
        <serialized byteorder="LE" bytepos="16"/>
        <deserialized alignment="1"/>
    </element>
</struct>
<struct alignment="1" name="tDynStruct" version="1">
    <element name="ui32SomeData" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="0"/>
        <deserialized alignment="1"/>
    </element>
    <element name="ui32DynArraySize" type="tUInt32" arraysize="1">
        <serialized byteorder="LE" bytepos="4"/>
        <deserialized alignment="1"/>
    </element>
    <element name="tVecDynamicArray" type="tVector" arraysize="ui32DynArraySize">
        <serialized byteorder="LE" bytepos="8"/>
        <deserialized alignment="1"/>
    </element>
</struct>

streammetatypes

Stream Meta Types are defined within the tags <streammetatypes> and </streammetatypes>. Example:

<streammetatypes>
    <streammetatype name="adtf/default" version="1">
        <property name="md_struct" type="string"/>
        <property name="md_definitions" type="string"/>
        <property name="md_data_serialized" type="bool"/>
    </streammetatype>
    <streammetatype name="test" version="1" parent="adtf/default">
        <property name="test_prop" type="tInt32"/>
    </streammetatype>
</streammetatypes>

The tag <streammetatype> uses the following attributes:

Name	Type	Required	Description
name	String	mandatory	The identifier of the stream meta type
version	UInt	mandatory	Version number of the specified stream meta type
parent	Text	optional	Identifier of a parent stream meta type

The tag <property> uses the following attributes:

Name	Type	Required	Description
name	String	mandatory	The name of the property
type	UInt	mandatory	The type of the property

predefined elements

The following base units are provided as default:

Base Unit Name	Description	Symbol
Metre	Fundamental unit for length	m
Kilogram	Fundamental unit for mass	kg
Second	Fundamental unit for time	s
Ampere	Fundamental unit for electric current	A
Kelvin	Fundamental unit for thermodynamic temperature	K
Mole	Fundamental unit for amount of substance	mol
Candela	Fundamental unit for luminous intensity	cd
Degree	Non-SI standard unit for angle	deg
Radiant	Non-SI standard unit for angle	rad
Unitless	No SI, but needed for own unit definitions
nou	No SI, but needed for no unit definitions

The following prefixes are provided as default:

Prefix Name	Power	Symbol
yotta	24	Y
zetta	21	Z
exa	18	E
peta	15	P
tera	12	T
giga	9	G
mega	6	M
kilo	3	k
hecto	2	h
deca	1	da
deci	-1	d
centi	-2	c
milli	-3	m
micro	-6	u
nano	-9	n
pico	-12	p
femto	-15	f
atto	-18	a
zepto	-21	z
yocto	-24	y

The following data types are provided as default:

Data Type Name	Description	Size
tBool	predefined ADTF tBool datatype	8
tChar	predefined ADTF tChar datatype	8
tUInt8	Upredefined ADTF tUInt8 datatype	8
tInt8	predefined ADTF tInt8 datatype	8
tUInt16	predefined ADTF tUInt16 datatype	16
tInt16	predefined ADTF tInt16 datatype	16
tUInt32	predefined ADTF tUInt32 datatype	32
tInt32	predefined ADTF tInt32 datatype	32
tUInt64	predefined ADTF tUInt64 datatype	64
tInt64	predefined ADTF tInt64 datatype	64
tFloat32	predefined ADTF tFloat32 datatype	32
tFloat64	predefined ADTF tFloat64 datatype	64

The following enums are provided as default:

Enum Name	Type</th
tMediaTypeMajor	tUInt32
tPixelFormat	tInt16