ADTF  3.12.8
DDL and ADTF 3


The DDL (Data Definition Language) is to describe memory content in a formal way.

So, it is possible to provide functionality, executables and utilities those are able to access and display data in a generic way:

The DDL will have some advantages over other ways to describe data like IDL (Interface Description Language), Protocol Buffers or FlatBuffers:

  • It describes only the layout of data in a common formal way! Each other description language format for describing data can be created.
  • This kind of data description makes it usable on and between cross-platforms, compiler-, architecure- and memory-layout independent machines.
  • The DDL does not force any specific method of serialization and deserialisation.
  • Describing data in DDL does not force you to use any code generation or toolings if you do not want that.
  • Reading data memory and the values via DDL Access methods does not mean, that the creator of that data must have created it with DDL writing methods.
  • You can dynamically describe your data in runtime.
  • All kinds of basic datatypes existing in C/C++ are supported. No restriction on that.
  • Direct access to structured content via C++-Code, the DDL will only describe that content.

There are also some disadvantages on DDL:

  • DDL is old fashioned XML, but it makes no sense to change to famous JSON, break the users code and confuse them.
  • No optimization while compile time, access methods will dynamically address values only in runtime.

Usage of Stream Meta Type "adtf/default"

The most important Stream Type instance within ADTF uses the default Stream Meta Type "adtf/default". (See also Stream Type and Stream Meta Type for a common definition)
This Meta Type is define in stream_meta_type_default. It will use 3 important properties:

md_struct
md_definitions
md_data_serialized


Note
It is very important to know, that many dynamic DDL functionality in ADTF does not require the default Stream Type itself but uses the properties "md_struct" and "md_definitions". See i.e. the compatibiliy functionality: Stream Meta Type "adtf/default".

In ADTF 2 the DDL File was an optional side-by-side file description next to the ADTF DAT File. It described the content of the DAT File.
Since the ADTF DAT File in ADTF 3 contains the complete DDL description if "adtf/default" Meta Type is used, only the units, datatypes, enums and structs tags are relevant. Within ADTF 3 we do not use the streammetatypes or streams tags anymore which are mentioned within DDL Definition File Format.

Methods to create valid DDL and "adtf/default"

Creating a DDL file and use it

It is possible to create a DDL file before you define any structured data within your code. To make sure the resulting DDL file is valid, we recommend to use the DDL Editor.

MD Generator Tool

ADTF provides a tool that creates C++ headers containing structure definitions and access classes from a given ADTF Media Description file (*.description).

If you are using the adtf_add_filter, adtf_add_streaming_service, adtf_add_system_service CMake macros, you only need to specify your description file within the sources of your target:

cmake_minimum_required(VERSION 3.10.0)
project(demo_code_generation)
find_package(ADTF COMPONENTS filtersdk)
adtf_add_filter(myfilter
myfilter.cpp
mytypes.description)

This will generate a header named after your description file, that you can include in your source files. In the above case:

#include <mytypes.h>

You may use following code within your filter if the DDL file contains any valid complex type (struct type) named "tMyType":

using namespace adtf::streaming;
using namespace adtf::mediadescription;
adtf::ucom::object_ptr<IStreamType> pMyDDLType = create_adtf_default_stream_type<tMyType>();

If you want the structure definitions to be generated in a namespace use the "MD_NAMESPACE" argument:

adtf_add_filter(myfilter
myfilter.cpp
mytypes.description
MD_NAMESPACE a::b::c)

If for some reasons you cannot use these macros, there is the adtf_md_generate_cpp CMake macro provided that will add header generation to existing targets.

The executable of the tool is accessible via the imported adtf::mdgen target.

An example of the usage of the generation facilities can be found at Demo Media Description Code Generation Filters Plugin.

Note
The generated header file will be directly accessible after the page_filter_base, page_streaming_service or System Service has been built for the first time. E.g Qt moc-files

Read the DDL file and setup Stream Type

It is also possible to read a file in code and create the description while runtime dynamically. To do so, please use the adtf_ddl::cDDLImporter and adtf_ddl::cDDLResolver.

using namespace adtf::ucom;
using namespace adtf::streaming;
using namespace adtf::mediadescription;
std::string oDDLFileFromConfig = "./mytypes.description";
//Import the file
ddl::cDDLImporter oFileImporter(oDDLFileFromConfig.c_str());
if (IS_FAILED(oFileImporter.CreateNew()))
{
throw std::runtime_error("configuration error, DDL file invalid");
}
//resolve the struct to a small description
ddl::cDDLResolver oDDLResolver("tMyType");
if (IS_FAILED(oDDLResolver.VisitDDL(oFileImporter.GetDDL())))
{
throw std::runtime_error("configuration error, Struct not defined in DDL file");
}
//create the type from imported file
object_ptr<IStreamType> pDDLType = create_adtf_default_stream_type("tMyType", oDDLResolver.GetResolvedXML());
//very important call, because ddl::cDDLImporter does not manage this!
delete oFileImporter.GetDDL();

Define DDL Description in code and use it

Use structure<> template

It is possible to use the type-reflection API provided via this package. It will create the necessary DDL description while runtime and compile-time:

using namespace adtf::ucom;
using namespace adtf::streaming;
using namespace adtf::mediadescription;
//we create a structure description and its default DDL type
struct tMyType
{
tInt32 m_nValue1;
tFloat64 m_fValue2;
};
auto oDescriptionForMyType = structure<tMyType>("tMyType");
oDescriptionForMyType.Add("m_nValue1", &tMyType::m_nValue1);
oDescriptionForMyType.Add("m_fValue2", &tMyType::m_fValue2);
object_ptr<IStreamType> pDDLType = create_adtf_default_stream_type(oDescriptionForMyType);

Define a huge string for DDL Description

This is a very old fashioned way to create your own DDL Decription. We do not recommend to use that, but for completeness it is specified here:

using namespace adtf::ucom;
using namespace adtf::streaming;
using namespace adtf::mediadescription;
//we create a structure description and its default DDL type
std::string strMyTypeString;
strMyTypeString += "<struct name=\"tMyType\" version=\"1\" arraysize=\"1\" alignment=\"1\">";
strMyTypeString += " <element type=\"tInt32\" name=\"m_nValue1\">";
strMyTypeString += " <deserialized alignment=\"1\"/>";
strMyTypeString += " <serialized bytepos=\"0\" byteorder=\"LE\"/>";
strMyTypeString += " </element>";
strMyTypeString += " <element type=\"tFloat64\" name=\"m_fValue2\">";
strMyTypeString += " <deserialized alignment=\"1\"/>";
strMyTypeString += " <serialized bytepos=\"4\" byteorder=\"LE\"/>";
strMyTypeString += " </element>";
strMyTypeString += "</struct>";
object_ptr<IStreamType> pDDLType = create_adtf_default_stream_type("tMyType", strMyTypeString.c_str());

Serialization of "adtf/default" Samples

The DDL describes the data layout in 2 separate representations:

Deserialized Memory Respresentation
The memory representation of data is the definition of value positions within RAM. To calculate the positions of the values within the memory only alignment, type information and arraysize are relevant attributes. Keep in mind: The byteorder attribute is absolutely not relevant here, because the values exists always in the same byteorder as the platform and the used compiler for that binary.
Serialized Respresentation
The serialized representation of data is the definition of values in a file or network. Within ADTF context this is the case storaging data in a DAT File or while sharing data at the IPC Sinks and Sources. To access the positions of that values and transform from one to the other one the bytepos, byteorder, type and arraysize are relevant attributes only.

We separate these representations to access the values in a fast way in memory, when deserialized and the deserialized representation will assure that data are described in such a formal way to use it on every single platform. It enables exchanging data between different architectures (big endian, little endian) and processors (Intel, ARM) vie network and file.

DDL Access to the Sample Content

Reading access via md_sample_data
Please note, that you are encouraged to use the md_sample_data template to access sample data via Media Descriptions (DDL), instead of using a decoder directly.
Reading access via DDLDecoder
To read data from a Sample you only need to use the ant::cStaticSampleDecoder or ant::cSampleDecoder.
Writing access via output_sample_data
If you're generating output samples, please use the adtf::streaming::flash::output_sample_data template with your structure definition. There is no need to fill samples via a codec.
Writing access via DDLCodec
To write data to a Sample you can use the ant::cStaticSampleCodec or ant::cSampleCodec.

Copyright © Audi Electronics Venture GmbH. All rights reserved. (Generated on Thu Aug 19 2021 by doxygen 1.8.14)