Improve TargetLink documentation

Change-Id: I97db0801183f5fa420e700f44b0a3c52e670a856
This commit is contained in:
Henrik Wahlqvist 2024-10-04 15:36:30 +02:00
parent 4e53b9818a
commit 35d3b16bb6
6 changed files with 49 additions and 43 deletions

@ -1,34 +1,35 @@
# Introduction of powertrain_build for new employee
# Introduction
[TOC]
<!--:powertrain_build:-->
## General powertrain_build Information
## General Information
[powertrain_build introduction](./powertrain_build.md) introduces installation and basic usage of powertrain_build.
[powertrain-build introduction](./powertrain_build.md) introduces installation and basic usage of powertrain-build.
## powertrain_build Code Base
## Code Base
The basic code introduction is placed in [powertrain_build General Code Introduction](./powertrain_build_architecture.md).
The basic code introduction is placed in [General Code Introduction](./powertrain_build_architecture.md).
## powertrain_build Deployment
## Deployment
Information on how to deploy powertrain_build can be found [here](./powertrain_build_deployment.md).
Information on how to deploy powertrain-build can be found [here](./powertrain_build_deployment.md).
## powertrain_build and Code Generators
## Code Generators
powertrain_build collects code generated from Simulink models in Matlab.
powertrain_build was based on working with TargetLink but also supports Embedded Coder (if set up correctly).
powertrain_builds contains code for generating code from Simulink models,
which can be found in *powertrain_build/matlab_scripts* folder.
powertrain-build collects code generated from Simulink models in Matlab.
powertrain-build was originally designed to work with TargetLink but
with the correct setup it can also support Embedded Coder.
For instance, Embedded Coder needs to be configured to mimic the variable classes.
The part of powertrain-build's codebase that processes Simulink models is located in *powertrain_build/matlab_scripts* folder.
For more information about the TargetLink setup see [this page](target_link/target_link.md).
## powertrain_build Development
## Development
If you want to develop powertrain_build, you can run it directly from the Git repositories.
You probably need a separate virtual environment, as any installed release versions of powertrain_build would interfere:
If you want to develop powertrain-build, you can run it directly from the Git repositories.
You probably need a separate virtual environment, as any installed release versions of powertrain-build would interfere:
```shell
python3 -m venv powertrain_build_venv

@ -6,27 +6,26 @@
## The Custom Code Block
The custom code block enables to easily insert custom written snippets of c code.
The custom code block makes it possible to easily insert custom written snippets of C code in the generated code.
Make sure to use a proper code review, as it is easy to cause underflow and overflow errors.
Make sure to use proper code review, as it is easy to cause underflow and overflow errors.
The usage of Polyspace Code Prover is advised.
It could also be an idea to run Polyspace bugfinder.
### Sharing the C Code
By deploying the generated c code from the custom code blocks to a common folder,
By deploying generated C code from custom code blocks to a common folder,
it can be shared between simulink models (similarily to [shared TargetLink functions](./functions.md)).
### Read the Manual
There are some docs in the TargetLink documentation DSPace docs under: Custom Code Blocks.
Also, there is a demo model, in the MATLAB Command Window, enter `tl_demos custom_blocks`.
There are some docs in the TargetLink documentation dSPACE docs under "Custom Code Blocks".
Also, there is a demo model in the MATLAB Command Window, enter `tl_demos custom_blocks`.
### Header Files
Include Statements in Custom Code blocks should not be used, but replaced by "AddFile" blocks.
Include statements in custom code blocks should not be used, but replaced by "AddFile" blocks.
This complies to MISRA rule 19.1.
Include directives which says that only preprocessor directives or comments may be placed before include directives.

@ -6,23 +6,23 @@
powertrain-build has two ways of handling diagnostics, depending on the use case.
The code for finding the diagnostics blocks can be seen in
The code for finding the diagnostics blocks can be found in
[parseCoreIdentifiers.m](https://opendev.org/volvocars/powertrain-build/src/branch/master/powertrain_build/matlab_scripts/CodeGen/parseCoreIdentifiers.m)
and
[parseDIDs.m](https://opendev.org/volvocars/powertrain-build/src/branch/master/powertrain_build/matlab_scripts/CodeGen/parseDIDs.m).
## Basics
All functions that are asking the core permission to run need to have an ID this is called a Function ID.
Permission to run can be withheld as a function of errors in the system, this is called Inhibition.
The relationship of which functions should be stopped for which faults (which are reported using an Event ID) is possible to calibrate.
Fail safes (Reconfigurations) use the same method/mechanism, but instead of stopping when an error is detected, they are activated.
All functions that are asking the core for permission to run need to have an ID this is called a Function ID.
Permission to run can be withheld due to errors in the system, this is called Inhibition.
The relationship between which functions should be stopped for which faults (which are reported using an Event ID) is possible to calibrate.
Fail safes (reconfigurations) use the same method/mechanism, but instead of stopping when an error is detected, they are activated.
### DTCs
An event ID is used for storing an event (Diagnostic Trouble Code (DTC)) in the Diagnostic Event Manager (DEM).
An event can be a detected fault, system not working according to specification or a placeholder where we might want to store additional information at the occurrence of the event.
The Stored events are DTCs when read with a tester.
The stored events are DTCs when read with a tester.
### DIDs
@ -192,7 +192,7 @@ There are six available function calls for each DID.
* Condition check function.
* Min and max condition check functions.
The metadata for each DID includes an ID and which of above functions should be generated or not including their respective data types.
The metadata for each DID includes an ID and which of above functions should be generated or not, including their respective data types.
Note that the same ID cannot be used for a function type more than once, as this would generate the same function call (overwrite).
There is one function type per DID function call, read_data, read_data_min, read_data_max, condition_check, condition_check_min and condition_check_max. The "nr_of_bytes" key is optional.

@ -7,7 +7,8 @@
## Why
To insert a function block in a subsystem will insert a function call in the C code generated from the model.
This will reduce the complexity numbers, increase testability and protect against memory problems if there is an interrupt and the function needs to be saved temporary to the memory.
This will reduce the complexity numbers, increase testability and protect against memory problems if there is an interrupt and
the function needs to be saved temporary to the memory.
## How
@ -24,9 +25,9 @@ There are two important aspects that need attention.
### Signal Feedback
When using feedback from a subfunction block to another subfunction of function in the model,
it is important to use the unit delay block when one uses function blocks.
Strangely one also needs a rename block after, since the unit delay block in this case can not have a readable signal configuration.
When using feedback from one subsystem block to another, it is important to use the unit delay block when one uses function blocks.
Strangely one also needs a [rename block](./naming_convention.md#rename-simulink-block) after,
since the unit delay block in this case can not have a readable signal configuration.
### Model Output Signals

@ -4,8 +4,8 @@
[TOC]
Some of the model blocks generates specific c-functions.
Examples of this are the lockup and the pre-lockup blocks as well as shared-libray blocks (custom code generation units).
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.
@ -84,7 +84,7 @@ If the option is deactivated the targetlink will execute the interpolation calcu
```txt
Example
The difference between two Int16 numbers can be greater than the maximum number
The difference between two Int16 numbers can be greater than the maximum number
which can be represented in Int16.
30000-(-30000)=60000 > 32767
```
@ -93,7 +93,7 @@ which can be represented in Int16.
## Creation of New Index and Interpolation Tables
Due to the different settings available there exists many table functions.
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:
@ -124,7 +124,7 @@ This though requires some manual editing of a newly created functions.
### Basics on Index Search and Interpolation
The index search outputs a fraction apart from the index, if chosen.
The index search outputs a fraction in addition to the index, if chosen.
**fraction:** f = (x - x[i])/(x[i+1] - x[i])
@ -134,8 +134,6 @@ which is then used by the interpolation block.
**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.
The above formulas are easily recognized in the c-code of the functions.
### Steps for Adding a New Table Function
A couple of steps are necessary when including a new index/interpolation function.
@ -160,9 +158,9 @@ In this case, it is the following 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 in the c-file.**
**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 not needed library reference")
![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).**
@ -214,7 +212,7 @@ 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.

@ -180,3 +180,10 @@ E.g. *EgrMonrArErrThd*, *BoostMonrPHiErrThd*.
Monitor Error Flag - \*Err, e.g. *EgrMonrArErr*.
Monitor Pass Flag \*Ok, e.g. *EgrMonrArOk* [Egr Area Ok], *VVTMonrPosnMaxOk* [VVT Position Max Ok].
## Rename Simulink Block
Sometimes it is useful to be able to rename signals in Simulink.
This can be achieved by creating a new mask, e.g. called "Rename_Signal",
which can contain a "TL_Inport" followed by an outport block.
The "TL_Inport" block can be configured with an appropriate name as wel as appropriate [variable_classes](./variable_classes.md).