278 lines
9.9 KiB
Markdown
278 lines
9.9 KiB
Markdown
# Diagnostics
|
||
|
||
-------------
|
||
|
||
[TOC]
|
||
|
||
powertrain-build has two ways of handling diagnostics, depending on the use case.
|
||
|
||
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 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.
|
||
|
||
### DIDs
|
||
|
||
DID is short for Data Identifier and is part of the Unified Diagnostic Services (UDS) protocol,
|
||
where it represents data items within an electronic control module (ECM) of a car.
|
||
DIDs can include things like sensor readings, actuator positions, and diagnostic trouble codes (DTCs).
|
||
DIDs are used to access and manipulate these data items through the UDS protocol, which allows for communication between diagnostic tools and the vehicle’s onboard computer.
|
||
|
||
## Using CSV Files
|
||
|
||
These files are generally stored in *\<repo-root\>/ConfigDocuments* but
|
||
can also be stored in *\<repo-root\>/Projects/\<PROJECT_NAME\>/ConfigDocuments*, however,
|
||
an update in *\<repo-root\>/Projects/\<PROJECT_NAME\>/ProjectCfg.json* is required for the latter.
|
||
|
||
### How to Define a Function ID Name
|
||
|
||
* Add the FiD (Function Identifier) in the sheet *CoreIdNameDefinition_FunctionIDs.csv*.
|
||
* Enter in which projects this FiD is to be defined in the project columns.
|
||
* All FiDs shall have the prefix *VcFi*, and all Fail safes shall have the prefix *VcFiFs*.
|
||
* If a used FiD is not configured in the core, the project will not compile.
|
||
|
||
|
||
|
||
### How to Add a Failsafe/Permission in a Model
|
||
|
||
This requires a special setup.
|
||
The block needs to be named "FiM_GetFunctionPermission" in order for powertrain-build to pick it up.
|
||
To handle this functionality it is currently recommended that this block uses a
|
||
[custom code block](./custom_code_block.md) to handle the functionality,
|
||
depending on the target.
|
||
|
||
A named constant is typically the input to this block.
|
||
|
||
### How to Define an Event ID Name
|
||
|
||
* Add the Event Id in the sheet *CoreIdNameDefinition_EventIDs.csv*.
|
||
* Enter in which projects these EvIds shall be defined in the project columns.
|
||
* All Event IDs shall have the prefix *VcEv*.
|
||
* If a used Event ID is not configured in the core, the project will not compile.
|
||
|
||
The structure of this csv file is the same as the one for Function IDs.
|
||
|
||
### How to Add Event Reporting in a Model
|
||
|
||
This requires a special setup.
|
||
There are typically one block per event type.
|
||
For example "Dem_SetEventStatus – Pre-Failed" block for reporting faults,
|
||
"Dem_SetEventStatus – Pre-Passed" block for reporting test passed.
|
||
"Dem_SetEventStatus – Failed" and "Dem_SetEventStatus - Passed" are also possible.
|
||
|
||
To handle this functionality it is currently recommended that this block uses a
|
||
[custom code block](./custom_code_block.md) to handle the functionality,
|
||
depending on the target.
|
||
|
||
A named constant is typically the input to these blocks.
|
||
|
||
### How to Define a DID
|
||
|
||
powertrain-build can read a few DID files depending on the use case and the data type of the DIDs.
|
||
Parsed DID files include *DIDIds_Float32.csv*, *DIDIds_FullRange_Float32.csv*, *DIDIds_FullRange_UInt32.csv* and *DIDIds_UInt32.csv*.
|
||
|
||
|
||
|
||
### How to Add a DID in a Model
|
||
|
||
This requires a special setup.
|
||
In order to get powertrain-build to collect DIDs,
|
||
create a new mask called "DID", it can contain a simple inport followed by an outport block.
|
||
|
||
### Generated DID Files
|
||
|
||
In terms of DIDs, powertrain-build will generate two sets C code.
|
||
The first set, named *VcDidDefinitions.c/h*, defines the DIDs in a struct and maps them to their hex IDs.
|
||
The second set, named *VcDIDApi.c/h*, defines the functions for retrieving the DIDs.
|
||
|
||
## Using YAML Files
|
||
|
||
### How to Define an Event ID Name (YAML)
|
||
|
||
Regarding Simulink blocks, the setup is the same as with [CSV files](#how-to-add-event-reporting-in-a-model).
|
||
|
||
Additionally, metadata for DTCs need to be added to a DTC configuration file (*ConfigDocuments/DTCs.yaml*).
|
||
|
||
The content of the file should be a yaml dictionary mapping DTCs to their corresponding hex value (event ID).
|
||
|
||
Example of a DTC definition file:
|
||
|
||
```yaml
|
||
{
|
||
"VcModelDtcOne": 0x123ABC,
|
||
"VcModelDtcTwo": 0xABC123,
|
||
"VcModelDtcThree": 0xFFFFFF
|
||
}
|
||
```
|
||
|
||
powertrain-build will generate two files, *VcCoreSupplierAbstraction.c/h*.
|
||
|
||
The header file maps the function e.g. `Dem_SetEventStatus(EventName, EventStatus)` (from a custom code block)
|
||
to a macro `VcCoreSupplierAbstraction_##EventName##_SetEventStatus(EventStatus)`.
|
||
|
||
The source file will contain all required DTC functions which in turn call the functions available in the target.
|
||
|
||
Example of *VcCoreSupplierAbstraction.h*:
|
||
|
||
```c
|
||
#ifndef VCCORESUPPLIERABSTRACTION_H
|
||
#define VCCORESUPPLIERABSTRACTION_H
|
||
|
||
/* Core API Supplier Abstraction */
|
||
|
||
#include "tl_types.h"
|
||
#include "Rte_LVC.h"
|
||
|
||
/* enum EventStatus {passed=0, failed=1, prepassed=2, prefailed=3} */
|
||
#define Dem_SetEventStatus(EventName, EventStatus) VcCoreSupplierAbstraction_##EventName##_SetEventStatus(EventStatus)
|
||
|
||
#include "PREDECL_CODE_ASIL_D_START.h"
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcOne_SetEventStatus(UInt8 EventStatus);
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcTwo_SetEventStatus(UInt8 EventStatus);
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcThree_SetEventStatus(UInt8 EventStatus);
|
||
#include "PREDECL_CODE_ASIL_D_END.h"
|
||
|
||
#endif /* VCCORESUPPLIERABSTRACTION_H */
|
||
```
|
||
|
||
Example of *VcCoreSupplierAbstraction.c*:
|
||
|
||
```c
|
||
#include "VcCoreSupplierAbstraction.h"
|
||
|
||
#include "CVC_CODE_ASIL_D_START.h"
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcOne_SetEventStatus(UInt8 EventStatus)
|
||
{
|
||
Rte_Call_DTC_123ABC_VcModelDtcOne_SetEventStatus(EventStatus);
|
||
return 0;
|
||
}
|
||
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcTwo_SetEventStatus(UInt8 EventStatus)
|
||
{
|
||
Rte_Call_DTC_ABC123_VcModelDtcTwo_SetEventStatus(EventStatus);
|
||
return 0;
|
||
}
|
||
|
||
UInt8 VcCoreSupplierAbstraction_VcModelDtcThree_SetEventStatus(UInt8 EventStatus)
|
||
{
|
||
Rte_Call_DTC_FFFFFF_VcModelDtcThree_SetEventStatus(EventStatus);
|
||
return 0;
|
||
}
|
||
|
||
#include "CVC_CODE_ASIL_D_END.h"
|
||
```
|
||
|
||
**NOTE:** each of the *Rte_Call_DTC_\** functions must be present in the target.
|
||
|
||
### How to Define a DID (YAML)
|
||
|
||
Regarding Simulink blocks, the setup is the same as with [CSV files](#how-to-add-a-did-in-a-model).
|
||
|
||
Additionally, metadata for DIDs need to be added to a DID configuration file (*ConfigDocuments/DIDs.yaml*).
|
||
Add the name of the file to the projects *ProjectCfg.json* file,
|
||
by adding a new element `"didDefFile": "DIDs.yaml"` in the *ProjectInfo* section.
|
||
|
||
There are six available function calls for each DID.
|
||
|
||
* Read data function.
|
||
* Min and max read data functions.
|
||
* 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.
|
||
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.
|
||
|
||
Example of a DID definition file:
|
||
|
||
```yaml
|
||
{
|
||
"dummy_did_one": {
|
||
"id": "DA00",
|
||
"data_type": "uint8",
|
||
"nr_of_bytes": 1,
|
||
"function_type": "read_data"
|
||
},
|
||
"dummy_did_two": {
|
||
"id": "DA00",
|
||
"data_type": "Dcm_NegativeResponseCodeType",
|
||
"function_type": "condition_check"
|
||
},
|
||
"dummy_did_three": {
|
||
"id": "DA01",
|
||
"data_type": "uint8",
|
||
"function_type": "read_data_max"
|
||
}
|
||
}
|
||
```
|
||
|
||
powertrain-build will generate two files, *VcDIDAPI.c/h*.
|
||
It contains the generated functions for each DID,
|
||
based on the data from the DID definition file as well as the unit configuration json file.
|
||
|
||
Example of *VcDIDAPI.h*:
|
||
|
||
```c
|
||
#ifndef VCDIDAPI_H
|
||
#define VCDIDAPI_H
|
||
|
||
#include "tl_basetypes.h"
|
||
#include "Rte_LVC.h"
|
||
|
||
#include "PREDECL_DISP_ASIL_D_START.h"
|
||
extern CVC_DISP_ASIL_D Bool dummy_did_one;
|
||
extern CVC_DISP_ASIL_D Bool dummy_did_two;
|
||
extern CVC_DISP_ASIL_D Bool dummy_did_three;
|
||
#include "PREDECL_DISP_ASIL_D_END.h"
|
||
|
||
#include "PREDECL_CODE_ASIL_D_START.h"
|
||
void DID_DA00_Runnable_ReadData(uint8 *Data);
|
||
void DID_DA00_Runnable_ConditionCheckRead(Dcm_NegativeResponseCodeType *ErrorCode);
|
||
void DID_DA01_Runnable_MAX_ReadData(uint8 *Data);
|
||
#include "PREDECL_CODE_ASIL_D_END.h"
|
||
|
||
#endif /* VCDIDAPI_H */
|
||
```
|
||
|
||
Example of *VcDIDAPI.c*:
|
||
|
||
```c
|
||
#include "VcDIDAPI.h"
|
||
|
||
#include "CVC_CODE_ASIL_D_START.h"
|
||
void DID_DA00_Runnable_ReadData(uint8 *Data)
|
||
{
|
||
memcpy(Data, &dummy_did_one, 1);
|
||
}
|
||
void DID_DA00_Runnable_ConditionCheckRead(Dcm_NegativeResponseCodeType *ErrorCode)
|
||
{
|
||
memcpy(ErrorCode, &dummy_did_two, sizeof(Dcm_NegativeResponseCodeType));
|
||
}
|
||
void DID_DA01_Runnable_MAX_ReadData(uint8 *Data);
|
||
{
|
||
memcpy(Data, &dummy_did_three, sizeof(uint8));
|
||
}
|
||
#include "CVC_CODE_ASIL_D_END.h"
|
||
```
|
||
|
||
**NOTE:** these functions must be present in the target.
|
||
|
||
## Notes
|
||
|
||
See [generateYamlInterfaceFile](../project_config.md#generateYamlInterfaceFile),
|
||
which makes powertrain-build read different files and generates different versions of the files
|
||
*VcDIDApi.c/h* and *VcCoreSupplierAbstraction.h*.
|