# Project Configuration Files

Configuration files needed by the build system.
The "entry point" is the project configuration file given as a command line argument to build.py.
This file can contain references to other configuration files and to the software [unit definition files](unit_config.md).

## Configuration Settings

### File Versioning

The build system compares the version information in the configuration files with the application version
to make sure a consistent configuration is used.

- "ConfigFileVersion": "0.2.1"
  - Project configuration file version.
- "BaseConfigFileVersion": "0.2.1"
  - Base configuration file version.
- "UnitsConfigFileVersion": "0.2.1"
  - Units configuration file version.

## Base Config

The base config file shares the same structure as the project config file and
can be used for non project-specific configuration settings and default values.

Example BaseConfig.json:

```json
{
  "BaseConfigFileVersion": "0.2.1",
  "ProjectInfo" : {
    "didDefFile": "DIDIds_FullRange",
    "srcCodeDstDir": "./output/SourceCode",
    "reportDstDir": "./output/Reports",
    "logDstDir": "./output/logs",
    "configDir": "../../ConfigDocuments",
    "interfaceCfgDir": "./Config/ActiveInterfaces",
    "prjUnitSrcDir": "../../Models/*/Vc*/pybuild_src",
    "prjUnitCfgDir": "../../Models/*/Vc*/pybuild_cfg",
    "prjUnitMdlDir": "../../Models/*/Vc*",
    "enumDefDir": "../../Models/Common/VcEnumDefinitions",
    "prjLocalDefs": "*_LocalDefs.h",
    "prjCodeswitches": "SPM_Codeswitch_Setup*.csv",
    "coreDummyFileName" : "VcCoreDummy",
    "featureHeaderName": "VcCodeSwDefines.h",
    "tsHeaderName": "VcUnitTsDefines.h",
    "useGlobalConst" : "VcConst"
  },
  "NvmConfig": {
    "fileName" : "vcc_nvm_struct",
    "baseNvmStructs" : "conf.local/nvm_structs.json"
  }
}
```

### NvmConfig

This key configures the NVM area sizes, and the filename of the c-files generated to defined the NVM.
The NVM is defined by six structs.
The reason for using c-structs is to guarantee the order the variables are declared in memory.
The c-standard does not specify in which order global variables are allocated in memory.
However, the standard says that struct members should be placed in memory in the order they are declared.

```json
{
  "NvmConfig": {
    "fileName" : "vcc_nvm_struct",
    "baseNvmStructs" : "conf.local/nvm_structs.json"
  }
}
```

### NvmStructs

This json file holds the order for NVM signals in the structs, it also holds area size and allowed signals.
We want to preserve the order for signals.
So signals should never be removed from this list.
If a signal is not used anymore it should not be removed, it should instead be marked with 'Position_*'.
E.g. Position_16Bit_195 the signal position will then be filled in by buildscript with signal found in model that's not found in the json.

```json
{
  "signals": [
    {
      "x_size": 1,
      "type": "Float32",
      "name": "sVcDtcIsc_Tq_NvmAdpnNC",
      "y_size": 1
    }
  ],
  "name": "NVM_LIST_32_PER",
  "default_datatype": "UInt32",
  "instanceName": "nvm_list_32_per",
  "includeStart": "MemMap_SDA_START.h",
  "includeStop": "MemMap_SDA_STOP.h",
  "size": 190,
  "persistent": true,
  "allowed_datatypes": ["Float32", "UInt32", "Int32"]
}
```

### fileName

This key defines the name of the c-files generated, which defines the NVM areas.

### ProjectTemplates

[ecuType](#ecutype) is used to separate different types of projects.
However, powertrain-build has, as of fda739bc13a2cdd9a3a72e8762fe8443cf6a88da,
been refactored so that it is possible to choose different options individually.

This key is used to set individual options to match the old ECU types, see example below.

```json
{
  "ProjectTemplates": {
    "Dummy": {
      "generalAsilLevelDebug": "B",
      "generalAsilLevelDependability": "B",
      "generateCalibrationInterfaceFiles": false,
      "useCalibrationRteMacroExpansion": false,
      "generateCoreDummy": true,
      "generateDummyVar": true,
      "generateInterfaceHeaders": false,
      "generateRteCheckpointIds": false,
      "generateYamlInterfaceFile": false,
      "includeAllEnums": false,
      "mapToRteEnums": false,
      "propagateTagName": true,
      "useA2lSymbolLinks": true,
      "useRteNvmStructs": false
    }
  }
}
```

Also see [CodeGenerationConfig](#codegenerationconfig) as the values in there take priority over these.

#### generalAsilLevelDebug

Set the ASIL classification for the generated debug and interface files.
Default is "B".

#### generalAsilLevelDependability

Set the ASIL classification for the generated "safe" debug and interface files.
Default is "B".

#### generateCalibrationInterfaceFiles

Generate calibration interface files, only available when "generateYamlInterfaceFile" is true.
Default is False.

These files can be used together with a certain type of calibration strategy in the Autosar environment known as double buffering.
The files generates a certain variable called "c\<swc_name\>\_TriggerReadRteCData" which can be toggled to read the rest of the calibration variables.
This makes the CPU not overload reading all the calibration variables from the RTE every iteration.

#### useCalibrationRteMacroExpansion

Redefine calibration variables as RTE calls.
Takes priority over "generateCalibrationInterfaceFiles" and is only available when "generateYamlInterfaceFile" is true.
Default is False.

Redefines calibration variables as RTE calls in an attempty to save memory.
Note that this increases CPU load.

#### generateCoreDummy

Generates a file defining dummy versions of functions towards e.g. supplier interface type functions.
Default is False.

#### generateDummyVar

Generates a file defining missing signals/variables between Simulink models/source code.
Default is False.

#### generateInterfaceHeaders

Generate interface header files, for more information see [MemoryMapConfig](#memorymapconfig).
Default is False.

Instead of generating required header files,
custom header files can be copied to the output foler by listing them in "includesPaths".
Paths should be relative to the location of *ProjectCfg.json* file.

#### generateRteCheckpointIds

Add RTE checkpoint ID definitions to the generated scheduling functions.

#### generateYamlInterfaceFile

Generate a yaml file containing all metadata for the project.
Default is False.

#### includeAllEnums

Include all enums found in the location pointed at by enumDefDir, even if the enums are not in use in the project.

#### mapToRteEnums

Map TL generated enum values in source code (all caps) to RTE style enums (camel case enum members defined as ints)
when those are defined, instead of defining the enum class from its TL-counterpart.
This overwrites how the enum members are mapped to integers as defined in the project.

#### propagateTagName

Add the Git tag to the file "vcc_sp_version.h". Currently only used for old Volvo projects.
Default is False.

#### useA2lSymbolLinks

Use "SYMBOL_LINK" in the generated A2L file.
Default is False.

#### useRteNvmStructs

Use the NVM struct definitions generated by the RTE instead of generating it ourselves.
Default is False.

## Rasters json File

### SampleTimes

The key "SampleTimes" defines the names of the available time rasters, and the value defines the scheduling time in seconds.

### Rasters

Each \<raster\> key defines which units that are scheduled in that raster,
the order of the list defines the order the units are executed within the raster.

## Project Config

The project config file contains project specific configuration settings and references to other configuration files.
It is a json file that should be located in the project root.
The project configuration file can override keys/values in the base configuration file.

Example ProjectCfg.json:

```json
{
  "ConfigFileVersion": "0.2.1",
  "BaseConfig" : "../../ConfigDocuments/BaseConfig.json",
  "UnitCfgs": "conf.local/rasters.json",
  "ProjectInfo" : {
    "projConfig" : "ABC_123",
    "a2LFileName": "A2L.a2l",
    "ecuSupplier" : "CSP",
    "ecuType" : "",
    "unitCfgDeliveryDir": "./output/UnitCfgs"
  }
}
```

### ProjectInfo

#### projConfig

The name of the project.
This name is used in all the configuration files to identify the project.

#### ecuSupplier

Ecu supplier name.
This is used to choose supplier dependent code generation (possibly in combination with ECU Type), e.g. the core dummy file generation.

#### ecuType

Ecu type name.
This is used to choose supplier dependent code generation (possibly in combination with ECU Supplier), e.g. the core dummy file generation.

#### unitCfgDeliveryDir

If this key is defined, the build system will deliver all the unit configuration files into the directory specified.

#### didDefFile

The name of the file defining all DIDs of the project.

#### srcCodeDstDir

The source code destination directory.

#### logDstDir

The log files destination directory.

#### configDir

The path to a folder containing all the configuration files of the project.
Used to find codeswitches, core-id and DID definition files.

#### interfaceCfgDir

The path to a folder with csv-files defining the supplier interface configuration.
The files shall be comma separated files, with the delimiter ';'.

The following files shall exists in the folder:
CAN-Input.csv, CAN-Output.csv, EMS-Input.csv, EMS-Output.csv, LIN-Input.csv, LIN-Output.csv, Private CAN-Input.csv and Private CAN-Output.csv.

#### prjUnitSrcDir

A file path where the superset of the source code files are found.
This path can/shall use wildcards.
E.g. "./Models/SSP*/Beta/Vc*/src", will match all folders under the Models folder which start with SSP,
and then all folders in Beta starting with Vc, which have a src folder.
The build system only includes files from software units referenced by the units config file.

#### prjUnitCfgDir

A file path to the unit definition files.
This file is a json file containing all the relevant meta data for the function.
E.g. input parameters, output parameters, calibration labels, local measurement variables, etc...
The unit definition file must match the filename pattern "config_*.json".

#### enumDefDir

Path to folder containing TL enum definition.

#### coreDummyFileName

Defines the file names of the dummy Core Identifier c code, which is generated by the build environment.

#### useGlobalConst

If declared, this module is included in the build. If the string is empty no module is included.

#### schedulerPrefix

Supply a prefix to use in the "common" functions and structs generated by powertrain-build.

### includesPaths

Use this key to list files that should be included in the source code.
Paths should be relative to the location of *ProjectCfg.json* file.

### CodeGenerationConfig

Use the field to choose specific code generation options in powertrain-build.
Key value pairs specified in this struct takes priority over the ones specified in [ProjectTemplates](#projecttemplates).
Afformentioned chapter also describes the available options and their default values.

### CompositionConfig

Collection of config options for autosar arxml based scheduling in the project configuration or base config.
These options affect the content of a configuration file used to complement the arxml file of the project
when building with conan.

```json
{
  "CompositionConfig": {
    "compositionName": "McLvcSafe",
    "compositionEnding": "yaml",
    "compositionArxml": "interface/McLvcSafe_GPA_17.arxml",
    "customYamlInitFunctionName": "dummy_init",
    "customYamlStepFunctionName": "dummy_step",
    "generateExternalImplementationType": false,
    "softwareComponentName":"LVCSC",
    "softwareComponentTemplate": "ARTCSC",
    "asil": "ASILD",
    "secure": true,
    "includeStatic": false,
    "includeShared": false,
    "includeDiagnostics": true,
    "includeNvm": true,
    "scaleMapsAndCurves": false
  }
}
```

#### compositionName

Name of the composition file used by conan to complement the arxml file.
Will be .yml unless name is given with file ending. see [compositionEnding](#compositionending).

#### compositionEnding

File ending of the generated yaml composition file.
Default is .yml.

#### compositionArxml

Name of the arxml file containing autosar packages and elements, specifying signal interfaces, data types etc.

#### customYamlInitFunctionName

Name of Init function.
Default is "AR_<scheduler_prefix>_VcExtINI".

#### customYamlStepFunctionName

Name of runnable function.
Default is "AR_<scheduler_prefix>_<runnable>".

#### generateExternalImplementationType

Specifies if external implementation types should be generated or not at the build stage (conan).
Default is True.

#### softwareComponentName

Name of the software component. Needs to match the software component name in the arxml.
Default is matching "A2lConfig/name".

#### softwareComponentTemplate

Name of template used by the software component.
Default is None.

#### asil

The ASIL level used by the software component.
Default is 'QM'.

#### secure

Determine if the software component is secure or not.
Will determine which set of SwAddrMethods is used.
Default is False.

#### includeStatic

Include static elements or not.
Default is True.

#### includeShared

Include shared elements or not.
Default is True.

#### includeDiagnostics

Include diagnostics elements or not.
Default is True.

#### includeNvm

Include non-volatile memory elements or not.
Default is True.

#### scaleMapsAndCurves

Include slope and bias to MAP and CURVE data types or not.
Default is True.

### MemoryMapConfig

This configuration is required when [generateInterfaceHeaders](#generateinterfaceheaders) is set to true.

Example:

```json
{
  "MemoryMapConfig": {
    "memMapPrefix": "DUMMY",
    "includeHeaderGuards": false,
    "includeMemMapForCalibration": false,
    "projectDefines": {
      "START": {
        "code": "#define DUMMY_START_SEC_CODE",
        "const": "#define DUMMY_START_SEC_CONST_UNSPECIFIED",
        "disp": "#define DUMMY_START_SEC_VAR_INIT_UNSPECIFIED",
        "cal": "#pragma section \".XcpCalibrationSection\""
      },
      "STOP": {
        "code": "#define DUMMY_STOP_SEC_CODE",
        "const": "#define DUMMY_STOP_SEC_CONST_UNSPECIFIED",
        "disp": "#define DUMMY_STOP_SEC_VAR_INIT_UNSPECIFIED",
        "cal": "#pragma section"
      }
    }
  }
}
```

#### memMapPrefix

Prefix of the generated memory map file, e.g. *DUMMY__MemMap.h*.

#### includeHeaderGuards

Adds header guards to e.g. *DUMMY__MemMap.h*.

#### includeMemMapForCalibration

Also adds the `#include "DUMMY__MemMap.h"` to the calibration header files.
Might not be necessary when using `#pragma section ".XcpCalibrationSection"`.

#### projectDefines

A dict with "START" and "STOP" keys each defining key value pairs for what to include in the header file
for code, constants, calibration variables and measurable variables.

See example above.