powertrain-build/docs/target_link/functions.md

# TargetLink Look-up and Pre-lookup Functions

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

[TOC]

Some of the model blocks generates its own functions in separate C files.
Examples of this are the lookup and the pre-lookup blocks as well as shared-libray blocks (custom code generation units).
The functions were generated once as c/h-files at one given time and are now called when used by the model functions.
The files are located under `Models/Common/pybuild_src`.
The look-up table uses a table index function and a table interpolation function.
TargetLink offers different Look-up tables in the TL library (tllib).

## Settings for Table Index Functions

The table index function have a number of settings defining the input and output variable types,
the type of search mechanism for finding the index and output configuration.
All of these settings define a specific c-function.

Examples of the settings and their meaning are given below.

### Table Index Search Methods (excerpt from the dSPACE Help)

* Linear search, start low.
`A linear search is implemented from the lowest end of the abscissa. The algorithm will go through the abscissa entries until a value higher than the input value is found. This search is simple and fast if the table is not too large.`
* Linear search, start high.
`A linear search is implemented from the highest end of the abscissa. The algorithm will go through the abscissa entries until a value lower than the input value is found. This search is simple and fast if the table is not too large.`
* Local search.
`The search starts at the index where the previous table value was found. Local searches can be slightly slower than linear searches due to the more complex code. This is recommended when the table inputs are smooth and do not change abruptly.`
* Binary search.
`The search area is divided into two halves, depending on whether the input value is in the upper or lower part. The iterations are repeated until the adjacent entries of the specified input value are found. This search is fast, especially in large tables, but the code is more complex.`

![tab_idx_search_method](../images/target_link/tab_idx_search_method.jpg "Different index search methods")

If the input data varies little or the change is smooth in relation to how often the function is calculated the `Local Search` is preferable.
E.g. temperatures, torques etc.

### Output Configurations

* Output only the index.
`Only the index signal is written to the block output. The block output is a scalar integer value in the range of the data type selected.`
* Separate output for index and fraction.
`Both the index and the fraction are written to the block output as separate signals. The block output is a vector with two elements, where the first element is the index and the second element is the fraction.`

**Warning:** If the option `Output only the index` is chosen, only the table indices are output which will limit the resolution.
This may not be wanted if e.g. the output shall be use in an interpolation map afterwards.
The calculation resource is though reduced.

![tab_idx_output_format](../images/target_link/tab_idx_output_format.jpg "Different output formats")

### Variable Type Definitions

Different variable data types are defined in the dSPACE data dictionary.
The most commonly used are `Float32, Unit32, Int32, UInt16, Int16, UInt8, Int8, Bool`.
The breakpoint type as well as the output type can be defined in the table index function.
The input type is also influencing the table index function.

![tab_idx_output_type](../images/target_link/tab_idx_output_type.jpg "The variable type can chosen both in the breakpoint and output")

**All the above settings decide the logic in the table index function.**

## Settings for Table Interpolation Functions

The interpolation function also have the same settings defining the input and output variable types as for table index functions
but it is also possible to define if interpolation shall be applied or not as well as dimension.
All of these settings define a specific c-function.
Examples of the settings and their meaning are given below.

### Activating Interpolation

The interpolation function is called only if interpolation is applied.
If deactivated, only an array in the code containing the indices is necessary.

### Dimension of the Interpolation Table

Defines the dimension of the table. 1D or 2D are supported.

### Distances Between Table Entries Less Than Half of Implemented Range

Targetlink provides the possibility to save memory if you can assure that the distance between the table entries are within the scaling range.
If the option is deactivated the targetlink will execute the interpolation calculation in double width of the operands, to avoid data loss.

**WARNING: Activate with extreme care! When this is chosen, be aware that that calibration can change the table entries thereby causing e.g. an overflow.**

```txt
Example
The difference between two Int16 numbers can be greater than the maximum number
which can be represented in Int16.
30000-(-30000)=60000 > 32767
```

![tab_int_settings](../images/target_link/tab_int_settings.jpg "Different settings for the interpolation table")

## Creation of New Index and Interpolation Tables

Due to the different settings available there exist many table functions.
If a suitable table function is found it is re-used.

A table function is re-used if:

* Input/output data types are identical.
* The search algorithms are identical.
* Interpolation Using Prelookup blocks.
  * Interpolation is on/off for all tables.
  * The number of dimensions is identical.
  * The distances between table entries less than half of implemented range checkbox is selected in the tables concerned.
* PreLook-Up Index Search blocks.
  * breakpoint data (e.g. data type).
  * The output configuration is identical.

If any of the above conditions are different another table function is needed.
For many settings there already exists a generated table function.
They are allocated under `Models/Common/pybuild_src` but if a new setting is detected the c-code for the new function needs to be generated.

In TargetLink 4.3 and onwards some of the operations needed in the index and interpolation tables have been integrated in TargetLink´s `Fixed Point Library`.
For example `DIV` (division), `MUL` (multiplication), `SHL` (shift left <<) or `SHR`(shift right >>).
The division/multiplication operations exist for all possible input and output data types.

As a result, if a new index or interpolation function is needed the functions are created using the Targetlink's fixed point library.

As the implementation of the new library would affect the different build scripts,
it has been decided to continue with the old structure ofthe index and interpolation functions and not use the fixed point library.
This though requires some manual editing of a newly created functions.

### Basics on Index Search and Interpolation

The index search outputs a fraction in addition to the index, if chosen.

**fraction:** f = (x - x[i])/(x[i+1] - x[i])

which is then used by the interpolation block.

**interpolation:** z = z[i] + f*(z[i+1] - z[i])

**Note:** x[i] represents the table indices, x the input value for the index search and z[i] the interpolation values with z as the output.

### Steps for Adding a New Table Function

A couple of steps are necessary when including a new index/interpolation function.
During code generation TargetLink automatically creates the c/h-files for the function.
It also includes the new function automatically in the models c-file.

The following steps are though necessary in order to edit and include the new table function:

* Include the header file of the table function in the project configurations common files `Projects\<your project>`.
* Update the c-file of the table function acccordingly, see below.
* Add the new files to the repository `Models/Common/pybuild_src/(Tab...)` together with your commit.

## Editing the Created C Code Files

To give some insight in the necessary steps two examples are given on how to edit an index table function and an interpolation function.

### Editing a New Table Index Function

In this case, it is the following function:

![tab_idx_function](../images/target_link/tab_idx_function.jpg "Example of an index table function")

In the example the input `x` and the table indices `x_table` are UInt32, the output though shall be UInt8.

**1. The reference to the fixed point library shall be removed from the c file.**

![tab_idx_edit_lib_ref](../images/target_link/tab_idx_edit_lib_ref.jpg "Removal of unneeded library reference")

**2. Correction of the fraction calculation. The formula above for calculation of the fraction is implemented in the code as below (left side).**

![tab_idx_edit_index_calc](../images/target_link/tab_idx_edit_index_calc.jpg "Editing the calculation of the fraction")

The naming of the libray functions gives a hint of what it does e.g. `C__U64SHLU32C6_LT32` is a left shift operation `SHL` of a UInt32 input, producing an UInt64 output.

The input is (x-x_table[0]), refer to (x - x[i]) in the fraction formula.
The usage of left shift and type casting to double width is needed to be sure to avoid a data loss when subtracting.
See [above](#distances-between-table-entries-less-than-half-of-implemented-range).

**Step-by-step:**

Converting the numerator part of the fraction formula:

```c
(UInt32) (x - x_table[0]) : Declaring that the input is UInt32

(UInt64) (UInt32) (x - x_table[0]) : Type casting to UInt64 (to avoid data loss)

((UInt64) (UInt32) (x - x_table[0])) << 8 : Left shift 8 bits
```

The second library function that is used is `C__U8DIVU64U32` i.e. dividing `DIV` a UInt64 operator with UInt32 operator producing an UInt8 output.
The fraction which is defined as irx[1] shall be output as UInt8 according to the function call in this case.

Declaring the denominator:

```c
(UInt32) (x_table[1] - x_table[0]) : Declaring that the denominator is UInt32
```

Calculation of the fraction (irx[1]):

Performing the division:

```c
(((UInt64) (UInt32) (x - x_table[0])) << 8) / ((UInt32) (x_table[1] - x_table[0]))
```

Assuring no data loss (using double width, UInt64):

```c
((UInt64)(((UInt64) (UInt32) (x - x_table[0]) << 8)) / ((UInt32) (x_table[1] - x_table[0])))
```

Type casting to Uint8:

```c
irx[1] = (UInt8) ((UInt64)(((UInt64) (UInt32) (x - x_table[0]) << 8)) / ((UInt32) (x_table[1] - x_table[0])))
```

**Removal of unused static variables.**

The fixed library functions needs to create some local variabels that are not needed when the calculation is performed in one step.

![tab_idx_remove_var](../images/target_link/tab_idx_remove_var.jpg "Editing the calculation of the fraction")

### Editing a New Interpolation Function

In this example we look into a 2D look-up table.
In order to calculate the output in this case, three subsequent interpolations needs to be performed.
See the below picture (excerpt from dSpace Help).

![tab_intp_theory](../images/target_link/tab_intp_theory.jpg "Interpolating 1D or 2D look-up tables")

The example funtion is

![tab_intp_function](../images/target_link/tab_intp_function.jpg "2D look-up function, output UInt32")

It has two UInt8 input axis `irx[2]` and `iry[2]` and an UInt32 output.
As seen above, three interpolations are needed in the function considering the inclination of the x- and y-curve using
a multiplication function `C__U64MULU32U16`for two UInt32 variables with an UInt64 output (using double width to avoid data loss).

In the fixed point library, Targetlinks needs to use a multiplication `C__U64MULU32U16`and shift right `C__U32SHRU64C6_LT32` to solve the interpolation.
The steps are the same as in the above example:

**1. The reference to the fixed point library shall be removed in the c-file.**

![tab_intp_edit_lib_ref](../images/target_link/tab_intp_edit_lib_ref.jpg "Removal of reference to the fixed point library")

**2. Correction of the interpolation calculation.**

![tab_intp_edit_intp_calc](../images/target_link/tab_intp_edit_intp_calc.jpg "Editing the calculation of the intepolation")

**3. Removal of unused static variables.**

![tab_intp_remove_var](../images/target_link/tab_intp_remove_var.jpg "Editing the calculation of the intepolation")

## dSpace Help topics for deep dive

In the dSpace Help there is more in-depth information. Please search for the text below and you will find the topics.

* Basics on Applying Output Calculation Methods (Lookup Methods).
* Basics on Applying Input Evaluation Methods (Search Methods).
* Table Function Names (Prelookup Block).
* Table Function Names (Interpolation Using Prelookup Block).