# TargetLink Variable Classes

-----------------------------

[TOC]

## General

The only variable classes to be used are CVC classes and the class `default`.
The classes are defined in the TargetLink data dictionary (.dd) file.
A list of the variable classes used by function developers beside `default` is given here.
The ASIL variable classes are used if the parameters shall be allocated to a specific monitored memory area.

![variable_classes](../images/target_link/variable_classes.PNG)

All variable classes are defined in TL DataDictionary.

## ASIL Classes

**NOTE:** Make sure to note the names of these classes (see image above).
Instead of the more simple name ["CVC_CAL"](#calibration-constants),
the ASIL A version of "CVC_CAL" would be "ASIL_A/CVC_CAL_ASIL_A".

Models using ASIL level variables should also mark its function calls as ASIL classed.
This is done by modifying the "FUNCTION" TargtLink block.

![function_block](../images/target_link/function_block.png)

TargetLink FUNCTION block with ASIL level.

Additionally, in order to get the correct ASIL level in the `config\_VcModelName.json` file,
the name of the model needs to be added to the struct "dependability_model_asil_class" in
`ConfigDocuments/matlab\_script\_config/CodeGen\_config.json`.

**NOTE:** The `Init function class` is generally not ASIL classified.
When we generate code, we only generate the main and restart (force box ticked) function calls.
These need to be ASIL classified.
Meaning the `Term function class` probably does not have to be ASIL classified either.

## CVC Classes

The variable unit must coincide with the abbreviation in the variable name.
See [naming convention](naming_convention.md).

![variable_properties](../images/target_link/variable_properties.jpg)

The macro `$L` uses the output line name in the variable name and the macro `$N` uses the model name,
so this variable will be named *rVcScrMdl_Z_ScrConcNoUs*.

All blocks with a CVC class output should have a filled in "Description".
If the variable is a calibration constant then if possible, determined "Max" and "Min" values should be set.
For local readables this is optional.

![variable_description](../images/target_link/variable_description.jpg)

Example of a CVC class variable with filled in description and Max/Min values.

## default Class

The `default` class should be used for all operations where a specific variable name in the code is unnecessary.

* The output line from a default class block should not have a line name.
  If a name must be visible for the documentation the name should have the ending `_DOC`.
* The output name should be `$S_$B`.
* "Min", "Max", "Unit" and "Description" should be empty.

![variable_default](../images/target_link/variable_default.jpg)

The Max, Min, Unit and Description fields should be empty and the name should be `$S_$B` for default class variables.

## External Signals

### General Info

The output variable name from all external out- and in-port blocks should be `$L`.

### Inport Blocks

The class should be `CVC_EXT` for all external inports.
The output line name from an inport block should be the complete variable name.

![variable_inport](../images/target_link/variable_inport.jpg)

Example of an inport with correct class, name and output line name.

### Outport Blocks

The class should be `CVC_DISP` for all external outports.
The input signal name to all external outports should be a long variable name propagated from an output line from a target link block
which has the output name `$S_$B` and the class `default`.

![variable_outport](../images/target_link/variable_outport.jpg)

This figure shows a correct implementation of a input signal to an outport block.

### External Variables

The properties for all external variables has to be filled in the interface description.
Although they are defines in the TargtLink models, the interface description is used to communicate with other consumers/senders.

## Constants

### Default Constants

If a constant is non-adjustable by calibration and needs no name for documentation,
a numeric value should be entered in the "Constant" dialog and the variable class should be `default`.

![variable_default_constant](../images/target_link/variable_default_constant.jpg)

Example of a `default` class constant.

### Unique Constants

If a constant should have a specific name and be used only once, the class should be `CVC_CONST`.
The block name should be `Vc_` + short name, e.g. `Vc_B_Init`.
The "output name" should be `c$B` and the output line name from the constant block should be empty.
If a name must be visible for documentation the line name should have the ending `_DOC`.
The constant value should come from a variable in workspace and must coincide with the output name.
For constants the Matlab workspace variable should be declared in *VcModelName_par.m*.

![variable_unique_constant](../images/target_link/variable_unique_constant.jpg)

Example of a unique constant.
The constant value is from the workspace variable `Vc.D_TosModeFailSafe` defined in *VcModelName_par.m* and
the variable name is `c$B` which gives the variable name `cVc_ D_TosModeFailSafe`.

### External Constants

If a constant with a specific name should be used more than once the class should be `CVC_CONST_EXT`.
The variable must also be declared in the model *VcConst.mdl*.
For an example of how this is done see figures below.
The constant value should come from a variable in workspace and must coincide with the output name.
For constants, the Matlab workspace variable should be declared in *VcModelName_par.m*.

![variable_external_constant](../images/target_link/variable_external_constant.jpg)

Example of an external constant.

![variable_vc_const](../images/target_link/variable_vc_const.jpg)

The external constant variable is implemented in a "TL_DataStoreMemory" – block in the model *VcConst.mdl*.

## Calibration parameters

### Calibration Constants

The output name of a calibration constant should be `c$N_$B`. The "output" type should be of class `CVC_CAL`.
The output line should not have a visible name.
The constant value should come from a variable in workspace and must coincide with the output name.

![variable_cal_constant](../images/target_link/variable_cal_constant.jpg)

Example of a calibration constant.

### Calibration Tables and Maps

All calibration lookup tables and maps should have a pre lookup block connected to their in-/out-ports.

* If possible the "VCC_Map_1D" should be used for lookup tables and "VCC_Map_2D" for lookup maps.
* For these blocks the lookup block name under the mask should be equal to mask name.
* All input value variables to booth the lookup and pre lookup blocks should coincide with the table/map names.
* The "breakpoint data" in the pre lookup block and the "table" in the lookup block should independently be one of the classes `CVC_CAL`.

### Calibration Tables

* The pre lookup block name should be mask name + `_x`.

![variable_cal_table](../images/target_link/variable_cal_table.jpg)

Example of the correct block names in a "VCC_Map_1D" block with the mask name `rt_CreepPedCmp`.

If the same pre lookup block is connected to more than one lookup map is allowed to ignore the rule above.
But the pre lookup name must be similar to the lookup map name and have the correct ending.

![variable_cal_pre_look_up](../images/target_link/variable_cal_pre_look_up.jpg)

Example of when the same prelookup block is connected to multiple lookup tables.

The length of the "breakpoint data" vector in the pre lookup block must be equal to the number of columns in the table matrix.
The "breakpoint" name in the pre lookup and the "table" name in the lookup table should be `t$N_$B`.

### Calibration Maps

The two pre lookup block names should be mask name + `_r` and mask name + `_c`.

![variable_cal_map](../images/target_link/variable_cal_map.jpg)

Example of the correct block names in a "VCC_Lookup2D" block with the mask name `rt_TiGear2`.

If the same pre lookup block is connected to more than one lookup map is allowed to ignore the rule above.
But the pre lookup name must be similar to the lookup map name and have the correct ending.

* The length of the "breakpoint data" vector in the pre lookup block "mask name_c" must be equal to the number of columns in the table matrix.
* The length of the "breakpoint data" vector in the pre lookup block  "mask name_r" must be equal to the number of rows in the map matrix.
* The "breakpoint" name in the pre lookup and the "table" name in the lookup table should be `m$N_$B`.

## Mergeable Calibration Variables

If a calibration variable should be used in more than one block, the variable must be have the class `CVC_CAL_MERGEABLE`.
The rules for mergeable calibration variables are the same as for normal calibration variables except in the following areas.
All blocks in a subsystem must have a unique name.
If it is necessary to use the same mergeable variable twice in the same subsystem the block names for these blocks should be hidden.
Instead, the name should be entered in the "block annotation", which can be found in the right-click menu under "block properties".
In this case it is no longer possible to us the macro `$B` for the variable name, instead this part of the name should be entered manually.

![variable_cal_mergeable](../images/target_link/variable_cal_mergeable.jpg)

Example when the same mergeable variable is used twice in the same subsystem.
In this case the block name is hidden and instead the name is entered in the "block annotation".
Since `$B` cannot be used the entered variable name is `c$N_M_ScrExhaustMol`.

![variable_cal_mergeable_example](../images/target_link/variable_cal_mergeable_example.jpg)

Example of Mergable table.

## Measurable Variables

### General About Measurable Variables

All non-external measure variables should have one of the classes `CVC_DISP`.
The output line name from a block with a measurable variable should be the short variable name.
The output name should be `x$N_$L` for all variables with type "Bool" (abbreviation "B") and `r$N_$L` for all other types.

![variable_measureable](../images/target_link/variable_measureable.jpg)

This figure shows the short output line name from a block with a CVC_DISP class output variable (red markings).
The output variable name starts with an "x" since the type is "Bool" (green markings).

### Measuring Output Variable from Masked Blocks

When measuring the output variable from a masked block it is important to remember that the variable is defined under the mask.
The line name can therefore not be entered on the output line from the masked block.
It must be entered on the output line under the mask and be propagated on the output line from the masked block.

![variable_measureable_masked](../images/target_link/variable_measureable_masked.jpg)

### Max and Min Settings for Measurable Variables

The use of "Max" and "Min" settings in blocks with class `CVC_DISP` is optional.
If "Max" and/or "Min" values are used then care must be taken.
"Max"/"Min" blocks lets you specify constrained range limits, which the code Generator assumes will never be exceeded (code optimization).
This leading range information is propagated through the model and can influence subsequent blocks.
This means that the code generator will remove "Max"/"Min" blocks in the signal chain if
they have the same value or a value outside of the set range of the processes signals.

![variable_measureable_min_max](../images/target_link/variable_measureable_min_max.jpg)

Example of "MinMax" block removed from the generated code,
because some signals had the same value ("8000") as signal in one of the min block inport.