DDL Mapper

Table of Contents

• Plugin Information
• Plugin Versions
• Component Information
• Properties
• Runner Pins
• Dynamic Pins
• Sources and Targets
  • Sources and corresponding Inpins
  • Targets and corrensponding Outpins
• Triggers
  • Data Triggered
    • Create sample on source updates
    • Create sample on source updates and a certain condition is set to true
  • Time Triggered
  • Create sample within a cyclic time
• Time Strategies

Plugin Information

Plugin Filename	adtf_core.adtfplugin
Plugin Description	adtf_core.plugindescription
Plugin Name	ADTF Core Plugin
License	ADTF Subscription
Support Mail	support@digitalwerk.net
Homepage URL	https://adtf.dev

Plugin Versions

Plugin Version	3.99.99
Plugin File Version	1.0
adtf	3.99.99
adtf::ucom	3.1.0

Component Information

Name	DDL Mapper
CID	ddl_mapping.filter.adtf.cid
Description	Use this filter to convert the content of DDL based samples from one or more incoming structured memory or plain type values to one or more outgoing structured memory or plain type value.
Type	Filter

Properties

Name	Value	Type	Description	Subproperties
default_trigger_time	0	tUInt32	Minimal default trigger time in ms (for targets with no trigger)	Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/fatal_action	2	tUInt32	The default action when a fatal error is reported.	Value List: Stop session = 2 Shutdown ADTF = 3 Abort to crash handler = 4Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/log_level	35	tUInt8	The log level for this channel.	Value List: None = 0 Error = 10 Warning = 20 Info = 30 Detail = 35 Dump = 40 All = 255Value Range: minimum = maximum = Filename Extension Filter:
log_channels/default/recoverable_action	0	tUInt8	The action to perform when a recoverable error is reported.	Value List: Log only = 0 Treat as fatal = 1Value Range: minimum = maximum = Filename Extension Filter:
mapping_file		cFilename	Filename for a *.map file that contains source and targets which can than be mapped to dynamic input/output pin.s	Value Range: minimum = maximum = Filename Extension Filter: Map files (*.map)
output_sample_time	0	tUInt8	Option to use whether the current timestamp of the trigger or the current clock timestamp for the output sample time.	Value List: While writing the output use the time of the sources sample time. = 0 While writing the output use the current trigger time. = 1Value Range: minimum = maximum = Filename Extension Filter:

Runner Pins

Name	Activation Type	Data Triggered	Data Input	Thread Triggered	Thread Cyclic	Timer Triggered	Timer Interval	Description
periodic_trigger	1	0		0	0	1	100	Runner to periodically trigger the function which generates the output data for periodic triggers within mapping file.

Dynamic Pins

Dynamic Input Pins	true
Dynamic Output Pins	true
Dynamic Input Binding Pins	false
Dynamic Output Binding Pins	false

Sources and Targets

The DDL Mapper is to convert the content of DDL based samples from one or more incoming structured memory or plain type values to one or more outgoing structured memory or plain type value.

To do so, the filter reads and interprets a DDL .map file. The mapping file will describe a mapping prescription what content to read and where to write it.

See ddl_mapping_specification for a full specification on that.

The file contains so called sources with a name and a set DDL type or plain type. Also, it contains targets with a name and a set DDL type or plain type. Targets will transcribed into outpin, sources are corresponding input pins.

We recommend to use the DDL Mapping Editor to create and edit map files. This tool is part of the DDL Utility package, which will be also redeployed within ADTF Configuration Editor package.

Following names and types are possible for sources (inpins) and targets (outpins):

Sources and corresponding Inpins

example of mapping file content	resulting input pin	possible assignment
<source name="NestedStruct_in"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </source>	Pin: input pin name: NestedStruct_in type: adtf/default with set md_struct="tNestedStruct" and md_definition="...here the ddl description of tNestedStruct..." Notice: The mapping file 2.0 is self contained and tNestedStruct must be described within the mapping file property type of the corresponding source.	On the targets following assignment example is possible: <assignment type="source"> <to>my_target_value_name</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<source name="x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </source>	Pin: input pin name: x type: adtf/plaintype with set c-type="INT64" and ddl type description set with md_struct="INT64" where only one element with the name value exists in the corresponding type. The corresponding ddl description will be automatically used. Notice: Following types are possible: BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64.	<assignment type="source"> <to>my_target_value_name</to> <source_name>x</source_name> <value_name>value</value_name> </assignment>
<source name="my_source_pin/NestedStruct"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </source>	Pin: input pin name: my_source_pin type: adtf/substreams substream name: NestedStruct substream type: adtf/default with set md_struct="tNestedStruct" and md_definition="...here the ddl description of tNestedStruct..." Notice: To use ADTF Substreams a special behaviour and naming syntax is defined. Within DDL Mapper only one pin will appear for my_source_pin and its substreams.	<assignment type="source"> <to>my_target_value_name</to> <source_name>my_source_pin/NestedStruct</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<source name="my_source_pin/x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </source>	Pin: input pin name: my_source_pin type: adtf/substreams substream name: x substream type: adtf/plaintype with set c-type="INT64" and ddl type description set with md_struct="INT64" where only one element with the name value exists in the corresponding type. Notice: Following substream types are possible: BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64	<assignment type="source"> <to>my_target_value_name</to> <source_name>my_source_pin/x</source_name> <value_name>value</value_name> </assignment>

Targets and corrensponding Outpins

example of mapping file content	resulting output pin	possible assignment
<target name="NestedStruct_out"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </target>	Pin: output pin name: NestedStruct_out type: adtf/default with set md_struct="tNestedStruct" and md_definition="...here the ddl description of tNestedStruct..."	Assignment if the source contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>my_source_pin/x</source_name> <value_name>value</value_name> </assignment> Assignment if the source does not contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="result"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </target>	Pin: output pin name: result type: adtf/plaintype with set c-type="INT64" and ddl type description set with md_struct="INT64" where only one element with the name value exists in the corresponding type. Notice: Following types are possible: BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64.	Assignment if the source contains substreams: <assignment type="source"> <to>value</to> <source_name>my_source_pin/NestedStruct</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment> Assignment if the source does not contains substreams: <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="my_target_pin/NestedStruct"> <properties> <property name="type">tNestedStruct</property> <property name="description"> <!-- ...here the ddl description of tNestedStruct... --></property> <property name="serialized">false</property> </properties> </target>	Pin: input pin name: my_target_pin type: adtf/substreams substream name: NestedStruct substream type: adtf/default with a set md_struct="tNestedStruct" and md_definition="...here the ddl description of tNestedStruct..."	<assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>"my_source_pin/x</source_name> <value_name>value</value_name> </assignment> or <assignment type="source"> <to>sSimpleStruct.ui8Val</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>
<target name="my_target_pin/x"/> <property name="type">INT64</property> <property name="description"> <!-- ...here the ddl description of plain type INT64... --></property> <property name="serialized">false</property> </target>	Pin: input pin name: my_target_pin type: adtf/substreams substream name: x substream type: adtf/plaintype with set c-type="INT64" and ddl type description set with md_struct="INT64" where only one element with the name value exists in the corresponding type. Notice: Following substream types are possible: BOOL, INT8, UINT8, INT16, UINT16, INT32, UINT32, INT64, UINT64, FLOAT32, FLOAT64	<assignment type="source"> <to>value</to> <source_name>"my_source_pin/x</source_name> <value_name>value</value_name> </assignment> or <assignment type="source"> <to>value</to> <source_name>NestedStruct_in</source_name> <value_name>sSimpleStruct.ui8Val</value_name> </assignment>

Triggers

The DDL Mapper will work either data triggered on each configured input pin or time triggered on the provided runner periodic_trigger.

For each target within the mapping file it is possible to configure if it is data triggered or time triggered:

Data Triggered

Create sample on source updates

The targets sample is transmitted, if data were received on `my_source_pin

<trigger type="source">
    <source_name>my_source_pin</source_name>
</trigger>

Create sample on source updates and a certain condition is set to true

The targets sample is transmitted, if data were received on NestedStruct_in AND the content of sSimpleStruct.ui8Val is equal than 3.

<trigger type="data">
    <source_name>NestedStruct_in</source_name>
    <value_name>sSimpleStruct.ui8Val</value_name>
    <operator>equal</operator>
    <value>3</value>
</trigger>

Time Triggered

Create sample within a cyclic time

The targets sample is transmitted, if the time trigger on periodic_trigger is called and the last call time is more than 10 milliseconds ago.

<trigger type="periodic">
    <time>10</time>
    <unit>ms</unit>
</trigger>

Time Strategies

To define which sample time is set to the resulting samples on outpin use the time_strategy of the trigger.

Additonally, it is possible to adjust "use sample time" or "use trigger time" on filters property "output_sample_time".

Trigger type	Time Strategy	output_sample_time	Used sample time on target
source or data	trigger	use sample time	target sample time is set to the sample time of the source sample this trigger belongs to
		use trigger time	target sample time is set to the trigger time of the trigger on inpin the sample was received
	earliest or latest	use sample time	target sample time is set to the earliest or latest sample time of the received source sample within all assignments
		use trigger time	target sample time is set to the earliest or latest trigger time of the received source sample within all assignments
	first_in_config	use sample time	target sample time is always set to the sample time of the received source sample used at first position in the assignement list
		use trigger time	target sample time is always set to the trigger time of the received source sample used at first position in the assignement list
periodic	trigger	use sample time	target sample time is set to the trigger time of the trigger. A change to "use sample time" has no effect
		use trigger time	target sample time is set to the trigger time of the trigger.
	earliest or latest	use sample time	target sample time is set to the earliest or latest sample time of the received source sample within all assignments
		use trigger time	target sample time is set to the earliest or latest trigger time of the received source sample within all assignments
	first_in_config	use sample time	target sample time is always set to the sample time of the received source sample used at first position in the assignement list
		use trigger time	target sample time is always set to the trigger time of the received source sample used at first position in the assignement list

If no trigger is configured within a target, the corresponding targets sample is transmitted each time the connected Active Runner triggers.
It is not possible to set up the connections to the input pins of this filter as asynchronous connections.