iTCHi Readme

Introduction

The iTCHi trace configuration helper is a program that helps users configure the winIDEA Analyzer to record OS and RTE aware hardware traces. You can find the Windows 64-bit executable itchi-bin.exe in the scripts/itchi directory of your winIDEA installation.

A graphical-user interface (GUI) is also available. To launch it, navigate to the OS tab under the Application settings in winIDEA. There, use the iTCHi Wizard button to launch the GUI. Note that the GUI is not necessarily self-explanatory and you probably want to continue reading this document.

You can call iTCHi with the --help flag to see available commands. The output of this command is also in the appendix.

$ itchi-bin.exe --help

By default iTCHi logs to itchi.log. If you encounter any problems with iTCHi add this log file to your support request. If you want to specify a different log file location you can do so via the --log flag.

$ itchi-bin.exe --log path/to/my_itchi.log

The rest of this document explains how to configure iTCHi for different use-cases. If you don’t have a basic understanding of OS Profiling and hardware tracing familiarize yourself with these concepts by reading the application note for your operating system¹ or request a training session from a TASKING FAE.

Basic Workflow

All commands follow a similar workflow; they take one or more input files (usually at least an ORTI file is required) and produce one or more output files such as an winIDEA Profiler XML file, a Profiler Inspectors JSON file², or a C file with instrumentation code.

The required input files, output files, and additional settings for the different commands are configured via a configuration file called itchi.json. By default iTCHi expects the configuration file in the current working directory, i.e. in the directory from where iTCHi is called. Alternatively, the location of the configuration file can be specified with the --config flag.

$ itchi-bin.exe --config path/to/itchi.json

The rest of this document consists of three parts. The next section explains how to set up the basic configuration of iTCHi via the itchi.json file. The second part describes the functionality of the different commands (i.e. command line flags), as well as the configuration attributes required to use them. Finally, the use-cases section explains the most common applications of iTCHi.

Basic Configuration

All iTCHi use-cases rely on a itchi.json configuration file. If you do not have such a file, you can generate an empty one with the --write_default_config flag.

$ itchi-bin.exe --write_default_config --config itchi.json

The use of --config is redundant here because the default itchi.json location is the same as the one specified in the call. You should now have an empty configuration file equal to the one in the appendix. Take a look at the configuration file.

You can see that there two top-level attributes called orti_file and profiler_xml_file that map to a string. All other attributes map to dictionaries (or objects if you prefer JSON terminology) with further attributes. The two top-level attributes are always required. All other objects are optional and only required for specific commands.

Start by configuring the ORTI file³ attribute. All OSEK/AUTOSAR Operating Systems can generate an ORTI file which contains information about OS objects such as Tasks, ISRs, and alarms. Refer to the documentation of your OS for how to enable the ORTI file generation. Once you have generated an ORTI file enter the absolute or relative path to the file (usually it has an .ORT or .ORTI file ending) to the configuration.

Important: All relative file paths in itchi.json are evaluated relative to the location of the configuration file. In other words, iTCHi uses the directory in which itchi.json is located as its working directory. The motivation for this was to make it easy to exchange configurations by adding them inside a winIDEA workspace directory. Absolute file paths are supported, too.

If you have a profiler.xml file you can add it to the profiler_xml_file attribute in the configuration file. If you do not have such a file yet, simply specify a non-existing file such as profiler.xml. iTCHi creates the file if it does not exist, otherwise it changes only those parts of the XML that are affected by the current command.

You can leave all other attributes as they are or remove them if you prefer a less cluttered configuration file. Remember that relative file paths are relative to the configuration file, and you will always at least need the orti_file and the profiler_xml_file attribute.

Important: iTCHi writes the ORTI file path into the Profiler XML file so that winIDEA can access it. Currently, iTCHi does not update the ORTI path to be relative to the Profiler XML file. To avoid issues, it is best to either create the profiler.xml in the same directory as itchi.json or to specify an absolute path to the ORTI file.

Your itchi.json file should now look as shown on the following listing. Make sure to remove trailing commas (i.e. commas behind the last attribute in a list or object).

{
    "orti_file": "path/to/Os_Trace.ORT",
    "profiler_xml_file": "profiler.xml"
}

You can now run iTCHi to generate your first Profiler XML file.

$ itchi-bin.exe --config itchi.json --running_taskisr

This should generate a profiler.xml file at that location you have specified. Open that file and verify that it references your ORTI file. It should also contain at least one Task and ISR object. Don’t worry about the contents in detail. With the help of iTCHi you should never have to edit the Profiler XML manually.

You can now record your first Task/ISR aware trace as explained in the winIDEA online help⁴. Make sure you specify the file type Profiler XML instead of ORTI in the Debug Operating Systems dialog. Point winIDEA to your newly generated Profiler XML file, and download or load symbols to apply the newly configured OS file.

The rest of this document assumes that you have a basic configuration file as explained in this section.

Commands

This section explains the available iTCHi commands and their configuration attributes. Each of the commands requires at least an orti_file and a profiler_xml_file in your itchi.json file. If you do not have at least these two attributes in your configuration read through the Basic Configuration section section first.

It is possible to combine multiple commands for a single call to iTCHi. For example, if you want to trace tasks and Runnables you can combine the --running_taskisr flag with the --runnable_instrumentation flag.

If you have an existing Profiler XML file iTCHi will only change the XML attributes related to the current command. For example, if you have received a Profiler XML that configures Task state tracing you can add Runnable tracing and iTCHi will leave the existing configuration as it is.

You can also specify commands via the commands attribute in the itchi.json. Generate the iTCHi default configuration file via --write_default_config and then change the desired command attributes under commands to true. These commands will always be active in addition to the ones specified via the command line.

Running Task/ISR

A Running Task/ISR trace records the currently running Task and ISR for each CPU core that runs an OSEK/AUTOSAR OS. This is the most basic form of tracing. Using the Profiler XML with this command is similar to using the ORTI file by itself. However, there are two reasons why it might still be necessary to use iTCHi to generate a Profiler XML: a missing default Task or ISR attribute, or a running Task or ISR expression containing pointers. For these cases add the following JSON object to your iTCHi configuration file.

{
    "running_taskisr": {
        "default_task": "",
        "default_isr2": "",
        "search_replace_list": [],
        "orti_core_to_soc_core": {},
        "orti_core_to_core_name": {}
    }
}

Default Task/ISR

ORTI specifies that the Running Task and the Running ISR2 attributes contain a value NO_TASK and NO_ISR respectively. These are the default values when no other task or ISR is active. winIDEA needs to be aware of these values to properly analyze a trace.

However, some operating systems do not follow the notion of NO_TASK/NO_ISR. In that case winIDEA might complain about a missing default Task or default ISR (no default IRQ). To work around this issue it is possible to specify a default Task and ISR via the iTCHi configuration file. For example, the new default task could be BackgroundTaskCore0.

iTCHi uses the following steps to decide which default Task and ISR is written into the Profiler XML file.

1. If a default ISR2 or Task is specified in the iTCHi config it is used.
2. If NO_ISR/NO_TASK is found in the ORTI file it is used.
3. If INVALID_ISR/INVALID_TASK is found in the ORTI file it is used.
4. Otherwise, the last element in the RUNNINGTASK/RUNNINGISR2 declaration is used.

Task/ISR expression with pointer

If the running Task or running ISR expression contains a pointer winIDEA might not be able to resolve the address. In this case iTCHi prints a warning and the expression can be changed via the configuration file. This makes sense for some operating systems where the running Task or ISR is accessible via a pointer, but also via a static symbol.

For example, if instead of OS_kernel_ptr[0]->isrCurrent the expression (OS_kernelData_core0).isrCurrent should be written to the Profiler XML file you can add the following two-item lists to the search and replace list.

"search_replace_list": [
  ["OS_kernel_ptr[", "(OS_kernelData_core"],
  ["]->isrCurrent", ").isrCurrent"]
]

iTCHi will iterate over the items and replace the first string with the second string for both the running Task and the running ISR expression.

Update AUTOSAR to physical core mapping

On SoCs with multiple Cortex-M and Cortex-A cores you might run into the situation that the AUTOSAR cores in the ORTI file do not match the physical cores in the real-world. For example, you might have only one AUTOSAR core that runs on the physical Cortex-M core of your SoC. That Cortex-M core might have the ID 3 in which case you would update the mapping as shown in the following listing.

"orti_core_to_soc_core": {
    "0": "3"
}

You might also want to rename a specific (ORTI) core to a more expressive name. For example, if you know that the ORTI core 0 on PowerPC has the name “CPU2”, then you could use the following mapping.

"orti_core_to_core_name": {
    "0": "CPU2"
}

Running Task/ISR tracing with BTF Export

In addition to writing the information for a running Task/ISR trace this command also adds the necessary information for a BTF trace export to the Profiler XML. This works by creating fake states for all Task and ISR profiler objects that are used by the BTF export algorithm to create the respective BTF events. The command uses the same configuration attributes as the regular Running Task/ISR command.

Running Task/ISR Sampling

There are cases when OS and RTE profiling is not feasible because hardware tracing is not available. In such cases, winIDEA Profiler Sampling can help you get an approximation of your Task and ISR load based on sampling (periodically reading) the Running Task and ISR variables.

Warning: Running Task and ISR Sampling does not guarantee exact metrics like hardware tracing. Instead, you get an approximation that becomes more accurate the longer you sample but might have systematic errors, for example, when an ISR executes for very short durations.

iTCHi can help you to create the correct Profiler XML for this use case. First, you need to create a default iTCHi configuration file that includes the orti_file and profiler_xml_file attributes, as explained in the Running Task/ISR section.

{
    "orti_file": "path/to/Os_Trace.ORT",
    "profiler_xml_file": "profiler.xml"
}

Then you can run iTCHi with the --running_taskisr_sampling flag. Before you start sampling, you have to set the Analyzer operation mode to None under Hardware - CPU Options.

Important: Make sure to set the Analyzer operation mode to None.

Now, point winIDEA to the generated Profiler XML file and open the Analyzer. Under Profiler OS Objects, you should find the Running Task/ISR objects with (SAMPLING) at the end. Make sure only to select these objects and start a recording.

You should now see the Task and ISR sampling data for the selected objects.

Task State Tracing with Single State Variables

For Running Task/ISR profiling there is no indication for why a task switch occurs. Different reasons for task switches are preemptions, waiting for events and terminations. ORTI specifies a STATE attribute for each task object to make this information accessible. The STATE attribute can either be a single variable or a more complicated expression consisting of multiple variables. The string OS_taskTableBase[27].dynamic->state is an example for a single variable (though the pointer is problematic), whereas the following string is considered a complex expression.

(((Os_ControlledCoreInfo[1U].RunningTask == Os_const_tasks[1]) * 1) & 1)
+ ((Os_ControlledCoreInfo[1U].ReadyTasks.p1 & 0x1) << 1)
+ ((Os_ControlledCoreInfo[1U].WaitingTasks.p1 & 0x1) << 2)";

If the task states in your ORTI file use complex expressions skip to Task State Tracing with Complex Expressions.

This command creates the Profiler XML suitable for state tracing with a single variable for each task. ISRs are still traced via RUNNINGISR2 and the configuration from Running Task/ISR applies.

For single core applications creating the Profiler XML from the ORTI file works automatically. For multi-core applications additional configuration is necessary because the ORTI file does not specify a core index attribute for tasks. There are different ways to specify the core indices in the iTCHi configuration file. If you are using a multi-core application add the following object to your configuration file.

"task_state": {
    "task_to_core_mapping": {},
    "task_to_core_heuristic": false,
    "autocore_os_config_h": "",
    "autocore_mk_gen_config_h": ""
}

There are three ways to get the task to core mapping:

1. Specify the core fore each task explicitly.
2. Reference an Os_config.h or Mk_Gen_Config.h file. This is the recommended way if you use the EB AutoCore OS.
3. Use a heuristic to extract the core ID from the STATE expression.

Note that the options are mutually exclusive, i.e., only one of them can be used at the same time. Remove the attributes for the options that you are not using.

Manually define task to core mapping

The attribute task_to_core_mapping points to a dictionary that maps from task names to core indices. iTCHi sets the core index for each task based on this mapping. If no mapping is available for a certain task iTCHi defaults to 0 and logs a warning. iTCHi does not report a mapping for a non-existent task.

The following shows an example mapping that maps task_a and task_c to core 0 while task_b is allocated to core 3.

"task_to_core_mapping": {
    "task_a": 0,
    "task_b": 3,
    "task_c": 0
}

Extract mapping from AutoCore Os_config.h file

Users of the EB AutoCore OS can point the autocore_os_config_h attribute to the OS_config.h file of their application. This file includes a structure with the core index as well as a non-pointer version of the state variable for each task.

For newer versions of AutoCore you might want to specify autocore_mk_gen_config_h instead. It depends on the exact version and chip architecture you are using.

"task_state": {
  "autocore_os_config_h": "Os_config.h"
}

iTCHi heuristic feature

iTCHi can try to find the core for each task. If task_to_core_heuristic is set to true iTCHi scans the task state formula with the regular expression [Cc]ore_?(\d+). If the formula matches the regular expression iTCHi assigns the respective number (\d+) to the task. If the regex does not match iTCHi assigns the core 0 to the task and logs a warning.

Task State Tracing with Complex State Expressions

For complex state variables (ORTI STATE attributes consisting of more than one variable) winIDEA Profiler Inspectors can be used to reconstruct the task state from multiple variables. This works by recording a running Task and ISR trace, tracing all variables that are part of the state formula, and combining the information via Inspectors.

This feature uses the iTCHi configuration options from the Running Task/ISR as well as the Task State with Single Variable sections. The running_taskisr configuration attribute is used for the configuration of the running Task and ISR trace. The task_state attribute is required to determine the task to core mapping for each task. Refer to the respective sections to learn how to configure those objects.

To configure the task state inspectors creation itself add the following object to your iTCHi configuration file.

{
    "task_state_inspectors": {
        "inspector_group_btf_states_prefix": "",
        "constant_variables": {},
        "create_data_areas": false,
        "create_preemption_aware_running_states": false,
        "default_state": "",
        "inspectors_file": "inspectors.json",
        "parent_area_template": "Data/{core_name}: Tasks/{task_name}",
        "reference_inspectors_file_from_xml": true,
        "task_core_to_core_name": {}
    }
}

Please refer to the appendix for additional documentation of the attributes.

Inspector Group BTF States Prefix

This attribute is helpful if you use Inspector groups. In that case, you can use it to specify the name of the Inspector group you use for the Inspectors so that BTF export still works.

Most users will not use groups and can remove this attribute or leave the empty string.

Constant Variables

The STATE expressions of some operating systems contain variables that are only written once at the start up of the application. If that initial write event is not traced the Inspectors cannot reconstruct the task state. To avoid this issue such variables can be set to a constant value. For example, consider the following expression.

OsCfg_Core_OsCore_Core0_Status_Dyn.OsState == 2 ?
  ( OsCfg_Trace_OsCore_Core0_Dyn.CurrentTask ==
    &OsCfg_Trace_Default_Appl_Init_Task ?
    0
    : OsCfg_Task_Default_Appl_Init_Task_Dyn.State )
  : 0xFF;

In this example the OsState is only initialized to 2 once when the application starts to execute. If that write is not recorded the expression as a whole cannot be evaluated. In this case it is best to to define that variable as a constant via constant_variables. This attribute is a dictionary that maps from variable names to integers.

"constant_variables": {
    "OsCfg_Core_OsCore_Core0_Status_Dyn.OsState": 2
},

Create Data Areas

You most likely want to set this attribute to true so that you don’t have to manually create data areas in the Analyzer. Keep in mind that you still have to make sure that the respective variables are traced.

"create_data_areas": true,

Default State

default_state specifies the initial state each task state Inspector. If the OS has an UNKNOWN state that is a good option. Otherwise, the SUSPENDED state is also a good default.

"default_state": "UNKNOWN",

Inspectors File

inspectors_file specifies the file to which the Inspectors are written. This file is referenced from the Profiler XML and should not be renamed or moved after iTCHi was executed. Since the Inspectors file format is JSON inspectors.json is a good default for this attribute.

"inspectors_file": "inspectors.json",

Reference Inspectors File from XML

You can also manually import the Inspectors into winIDEA. In that case, set the attribute reference_inspectors_file_from_xml to false so that iTCHi removes the reference to the Inspectors file from the Profiler XML file.

"reference_inspectors_file_from_xml": true,

Parent Area Template

Each task state inspector is created under the running task node for its task. The parent_area_template attribute specifies the path to that node. The string contains two format expressions that are replaced by iTCHi with the core_id and the task_name of each task state inspector. You can omit this attribute and it will default to the following value.

"parent_area_template": "Data/Core {core_id}: Tasks/{task_name}",

Task State Tracing with Complex State Native

For complex state variables (ORTI STATE attributes consisting of more than one variable), the winIDEA Analyzer has the capability to reconstruct the task states if all variables in the state formula are part of the trace recording.

This feature uses the iTCHi configuration options from the Running Task/ISR sections to remap AUTOSAR cores and remove pointers from the Running TASK or ISR expressions.

Note: This command effectively replaces complex state profiling via Inspectors and should be used instead.

The following snippet shows the iTCHi configuration for this command.

{
    "task_state_complex": {
        "constant_variables": {},
    }
}

Constant Variables

The STATE expressions of some operating systems contain variables that are only written once at the start up of the application. If that initial write event is not traced the Inspectors cannot reconstruct the task state. To avoid this issue such variables can be set to a constant value. For example, consider the following expression.

OsCfg_Core_OsCore_Core0_Status_Dyn.OsState == 2 ?
  ( OsCfg_Trace_OsCore_Core0_Dyn.CurrentTask ==
    &OsCfg_Trace_Default_Appl_Init_Task ?
    0
    : OsCfg_Task_Default_Appl_Init_Task_Dyn.State )
  : 0xFF;

In this example the OsState is only initialized to 2 once when the application starts to execute. If that write is not recorded the expression as a whole cannot be evaluated. In this case it is best to to define that variable as a constant via constant_variables. This attribute is a dictionary that maps from variable names to integers.

"constant_variables": {
    "OsCfg_Core_OsCore_Core0_Status_Dyn.OsState": 2
},

Task State Tracing with Instrumentation

This command utilizes the OS hooks to generate Task and ISR events by either writing into a global variable or using an instrumentation trace technique (such as RH850 software trace).

Task state tracing is currently supported for the Vector MICROSAR OS via the --task_state_instrumentation_microsar flag and for EB AutoCore via --task_state_instrumentation_autocore.

Vector MICROSAR

For MICROSAR, the following configuration section is required.

{
    "task_state_inst_microsar": {
        "vector_os_timing_hooks_h": "Os_TimingHooks_isystem.h",
        "vector_os_timing_hooks_c": "Os_TimingHooks_isystem.c",
        "instrumentation_type": "data_trace",
        "software_based_coreid_gen": true,
        "trace_variable": "isystem_trace",
        "trace_variable_definition": "",
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "sft_dbpush_register": 0
    }
}

iTCHi supports different types of instrumentation. Set the instrumentation_type attribute to data_trace, stm_trace, or software_trace depending on the approach you are using. This will also effect the generate instrumentation files.

For data_trace, use trace_variable to specify the name of the trace variable.

For stm_trace, use stm_base_address and stm_channel to specify the respective values. Both values must be hex-strings, i.e., start with 0x.

For software_trace, use db_push_register to specify the DB push register.

Elektrobit AutoCore

For AutoCore, the following configuration section is required.

{
    "task_state_inst_autocore": {
        "dbg_h": "Dbg.h",
        "dbg_c": "Dbg.c",
        "trace_variable_task": "isystem_os_task",
        "trace_variable_isr": "isystem_os_isr"
    }
}

Runnable Tracing with Instrumentation

Runnable tracing is an important feature to get deeper insights into the behavior of an application. Runnables can be traced via program flow trace or via instrumentation utilizing data trace. While program flow trace works without instrumentation it produces short trace durations for most setups. Instrumentation based tracing is good compromise as it generates significant longer traces while keeping the instrumentation as minimal as possible.

Instrumented tracing works by utilizing the VFB trace feature of the AUTOSAR RTE. VFB trace enables the user to generate instrumentation hooks for Runnables and other RTE objects of interests. Once you have activated the hooks in your RTE generation tool iTCHi helps to implement the instrumentation and to make winIDEA aware of the Runnable identifier to Runnable name mapping. To use this feature add the following object to your iTCHi configuration file.

{
    "runnable_instrumentation": {
        "isystem_vfb_hooks_c": "",
        "rte_hook_h": "",
        "rte_xdm": "",
        "regex": "(FUNC\\(void, RTE_APPL_CODE\\) Rte_Runnable_(\\w+)_(Start|Return)\\([^\\n]+\\))",
        "trace_variable": "isystem_trace_runnable",
        "template_file": "",
        "instrumentation_type": "data_trace",
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "db_push_register": "0x0"
    }
}

The isystem_vfb_hooks_c attribute specifies the location of the instrumentation file that is generated by iTCHi. At the moment VFB tracing is supported for Vector MICROSAR OS and Elektrobit AutoCore OS. For the former point rte_hook_h to the Rte_Hook.h header file. For the latter point rte_xdm to the Rte.xdm file of your tresosStudio project.

iTCHi uses the regex to extract Runnable hooks from Rte_Hook.h. If you are unsure, just leave this attribute as it is. For more information see the next section.

Note: iTCHi allows you to provide your own Runnable instrumentation template. To start simply point template_file to a non-existing file. iTCHi will write the default template into that location for you. You can then adapt it to your needs.

iTCHi comes with default instrumentation templates. The template_file attribute allows you to specify a custom template. If you point template_file to a non-existing file iTCHi will write the default template into this file. If you leave the attribute empty or remove it the default template file is used.

Refer to the previous section for an explanation of the instrumentation_type, trace_variable, stm, and db_push_register attributes.

Runnable Instrumentation with Vector MICROSAR OS

DaVinci Configurator writes the active RTE hooks into Rte_Hook.h during the RTE code generation step. iTCHi extracts those hooks from the header file, assigns an identifier and writes them into the Profiler XML and the isystem_vfb_hooks_c file.

The following regular expression (regex) is used to find hooks within the header file. The outer parentheses are simply Python’ss way of allowing multi-line strings. The parentheses inside the string specify matching groups.

regex = ("("
         "FUNC\(void, RTE_APPL_CODE\) "
         "Rte_Runnable_" "(\w+)" "_(Start|Return)" "\([^\\n]+\)"
         ")")

You can overwrite the default regex via the regex attribute within runnable_instrumentation. If you create a default iTCHi file with --write_default_config it will contain the default regex that you can adapt to your needs. Keep in mind that \ and " have to be escaped in the JSON file. Also regular parentheses are used for grouping in Python⁵. For example, (foo) specifies a group that matches the string foo. If you want to use groups yourself be sure to make them non-capturing with (?:foo), because iTCHi relies on exact the four groups that are part of the default regex.

Runnable Instrumentation with Elektrobit AutoCore OS

EB tresosStudio stores active RTE hooks in the Rte.xdm XML file. iTCHi is able to parse this file and extract all active Runnable hooks. The rest works similar to MICROSAR OS; iTCHi assigns an identifier to each Runnable, generates the instrumentation and writes the identifier to name mapping into the Profiler XML file.

Running Task/ISR tracing with OS Signaling

Not supported.

Task/ISR tracing with additional OS Signaling gives the Profiler the information whether a task context switch was caused by a preemption, termination or waiting transition. This information is signaled with an additional ORTI Attribute vs_OSSIGNAL and is only supported by ETAS RTA-OS. If you need support for this feature contact a TASKING FAE.

Runnable Program Flow

Runnables are functions and can be recorded via Program Flow trace. The Profiler XML file can specify which functions should be treated as Runnables. This has two benefits. First, the Runnables are shown under a dedicated node in the Profiler timeline. Second, the functions that are marked as Runnables are included in the BTF export for analysis in third party timing-tools.

Add the runnable_program_flow object to your iTCHi configuration file. runnables is a list of function symbols that will be added to the Profiler XML as a Runnable.

{
    "runnable_program_flow": {
        "runnables": [
            "first_runnable",
            "second_runnable"
        ]
    }
}

Once you have added the Runnables to the Profiler XML file run iTCHi with the --runnable_program_flow flag.

Signals

The term signal means a single global variable. The winIDEA Analyzer can display global variables via data areas. Alternatively, you can configure signals in the Profiler XML. The biggest advantage of this approach is that winIDEA exports these signals into BTF.

To add signal objects to the Profiler XML, create a signals configuration object, and then add signals via a second signals attribute that points to a list of strings.

{
    "signals": {"signals": ["foo", "bar", "quz"]}
}

Spinlock with Instrumentation

Information: This command currently only supports the Vector MICROSAR OS Timing-Hooks.

Please contact your TASKING FAE if you want to use spinlock profiling.

Use-Cases

This section helps you to find out which of the iTCHi flags (or commands) you need for your use-case. Read through the different parts and note which flags you need. You can then got to the command section above. You will find a separate section explaining each of the commands you have written down. Once you have configured each command separately you can run iTCHi with all flags combined.

Please, also refer to our AUTOSAR Classic Profiling Application Note if you are not sure which use-cases you need.

Basic Task/ISR Timing-Analysis

If you are just getting started you want to use Running Task/ISR profiling first. Use the --running_taskisr flag if you want to analyze the data only in winIDEA or --running_taskisr_btf if you want to export the data into a third party timing-tool in the BTF trace format.

You can use iTCHi for this use-case if you have data trace available. If you have RH850 Software Trace available, use task state tracing via instrumentation and select RH8850 Software Trace as the instrumentation technique.

Advanced Task/ISR Timing-Analysis

If the information about the currently running Task and ISR is not enough for your analysis you can record the task states. You have to look into your OS ORTI file to find the right approach. If the TASK STATE expression for your tasks is a single symbol (e.g. OS_task_states[3]) you want to use --task_state_single_variable.

If you see a more complex expression you can use --task_state_complex_native. Note that this requires a higher number of data trace comparators since each of the symbols that are part of the expression have to be recorded. If you do not have enough data trace comparators you might have to use instrumentation with the --task_state_instrumentation command.

Task state tracing requires data trace in most cases. If you do not have enough data trace comparators you might have to fall back to basic Task/ISR analysis. Software trace is supported via instrumentation. In that case the configuration needs to be done manually. Task state tracing is not supported with program-flow trace.

Runnable Tracing

If you want to go beyond task/ISR analysis you can use Runnable tracing. If you have data or software trace only you need to use instrumentation to record Runnables. The --runnable_instrumentation command helps with that use-case. If you have program-flow trace you can record Runnables with the --runnable_program_flow command. Note that you might want to use instrumentation even if you have program-flow trace to record longer traces or more Runnable objects.

Appendix

iTCHi help

usage: itchi.py [-h] [--config config] [--log_file log_file] [--write_default_config] [--arti] [--running_taskisr] [--running_taskisr_btf] [--running_taskisr_sampling]
                [--running_taskisr_ossignaling] [--task_state_single_variable] [--task_state_complex_expression] [--task_state_complex_native] [--task_state_instrumentation_microsar]
                [--task_state_instrumentation_autocore] [--runnable_instrumentation] [--runnable_program_flow] [--signals] [--spinlock_instrumentation_microsar] [--log_trace_symbols]
                [--version]

iTCHi Trace Configuration Helper

optional arguments:
  -h, --help            show this help message and exit
  --config config       path to config file (default: itchi.json)
  --log_file log_file   path to log file (default: itchi.log)
  --write_default_config
                        Writes an empty configuration file and exits.
  --arti                Creates profiler XML and instrumentation code for tracing as specified by the ARTI standard.
  --running_taskisr     Prepares profiler XML for running Task/ISR tracing.
  --running_taskisr_btf
                        Same as --running_taskisr but with BTF export.
  --running_taskisr_sampling
                        Profiler XML for running Task/ISR sampling.
  --running_taskisr_ossignaling
                        Not supported via iTCHi. Import ORTI directly.
  --task_state_single_variable
                        Prepares profiler XML for task state tracing based on a single variable for each task.
  --task_state_complex_expression, --task_state_inspectors
                        Prepares profiler XML and Inspectors for task state tracing with complex expressions.
  --task_state_complex_native
                        Prepares profiler XML for native task state tracing via complex expressions.
  --task_state_instrumentation_microsar, --task_state_instrumentation
                        Creates profiler XML and instrumentation code for state tracing with the Vector MICROSAR OS.
  --task_state_instrumentation_autocore
                        Creates profiler XML and instrumentation code for state tracing with the EB AutoCore OS.
  --runnable_instrumentation
                        Prepares profiler XML for instrumented Runnable tracing and creates instrumentation.
  --runnable_program_flow
                        Prepares profiler XML for Runnable tracing based on program flow trace.
  --signals             Prepares profiler XML for signals.
  --spinlock_instrumentation_microsar, --spinlock_instrumentation
                        Experimental: prepares profiler XML for spinlock profiling.
  --log_trace_symbols   Logs symbols that have to be traced for current Profiler XML.
  --version             Prints build date and exits.

Config attributes

Empty itchi.json

{
    "orti_file": "OS.ort",
    "profiler_xml_file": "profiler.xml",
    "running_taskisr": {
        "default_task": "",
        "default_isr2": "",
        "search_replace_list": [],
        "orti_core_to_soc_core": {},
        "orti_core_to_core_name": {}
    },
    "task_state": {
        "task_to_core_mapping": {},
        "task_to_core_heuristic": false,
        "autocore_os_config_h": "",
        "autocore_mk_gen_config_h": ""
    },
    "task_state_inspectors": {
        "inspector_group_btf_states_prefix": "",
        "constant_variables": {},
        "create_data_areas": false,
        "create_preemption_aware_running_state": false,
        "default_state": "",
        "inspectors_file": "inspectors.json",
        "parent_area_template": "Data/{core_name}: Tasks/{task_name}",
        "reference_inspectors_file_from_xml": true,
        "task_core_to_core_name": {}
    },
    "task_state_complex": {
        "constant_variables": {}
    },
    "task_state_inst_microsar": {
        "vector_os_timing_hooks_h": "Os_TimingHooks_isystem.h",
        "vector_os_timing_hooks_c": "Os_TimingHooks_isystem.c",
        "instrumentation_type": "data_trace",
        "software_based_coreid_gen": true,
        "trace_variable": "isystem_trace",
        "trace_variable_definition": "",
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "sft_dbpush_register": 0
    },
    "task_state_inst_autocore": {
        "dbg_h": "Dbg.h",
        "dbg_c": "Dbg.c",
        "trace_variable_task": "isystem_os_task",
        "trace_variable_isr": "isystem_os_isr"
    },
    "runnable_instrumentation": {
        "isystem_vfb_hooks_c": "",
        "rte_hook_h": "",
        "rte_xdm": "",
        "regex": "(FUNC\\(void, RTE_APPL_CODE\\) Rte_Runnable_(\\w+)_(Start|Return)\\([^\\n]+\\))",
        "trace_variable": "isystem_trace_runnable",
        "trace_variable_definition": "",
        "template_file": "",
        "instrumentation_type": "data_trace",
        "software_based_coreid_gen": true,
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "sft_dbpush_register": 0,
        "sft_dbtag": true
    },
    "runnable_program_flow": {
        "runnables": [],
        "csv_file": "",
        "csv_column_name": "",
        "csv_column_id": ""
    },
    "signals": {
        "signals": []
    },
    "spinlock_inst_microsar": {
        "spinlock_trace_variable": "isystem_trace_spinlock",
        "spinlock_trace_variable_definition": ""
    },
    "arti": {
        "os_trace_variable": "arti_os_trace",
        "rte_trace_variable": "arti_rte_trace",
        "os_trace_c": "ARTI_Os_Trace.c",
        "os_trace_h": "ARTI_Os_Trace.h",
        "rte_trace_c": "ARTI_Rte_Trace.c",
        "rte_trace_h": "ARTI_RTe_Trace.h",
        "software_based_coreid_gen": false
    },
    "commands": {
        "arti": false,
        "running_taskisr": false,
        "running_taskisr_btf": false,
        "running_taskisr_sampling": false,
        "task_state_single_variable": false,
        "task_state_complex_expression": false,
        "task_state_complex_native": false,
        "task_state_instrumentation_microsar": false,
        "task_state_instrumentation_autocore": false,
        "runnable_instrumentation": false,
        "runnable_program_flow": false,
        "signals": false,
        "spinlock_instrumentation_microsar": false,
        "log_trace_symbols": false
    }
}

Changelog

• 27-Oct-2023
  • Update company name at many (but not all) locations.
    
• 21-Sep-2023
  • Fix spelling error in BTF transition from Unknown to Terminated (the d was missing).
• 21-Jul-2023
  • Fix issue that MICROSAR thread and spinlock instrumentation definitions don’t have a newline.
• 28-Jun-2023
  • Fix issue that trace_variable is not rendered into trace_variable_definition for runnables.
• 20-Jun-2023
  • Split task_state_instrumentation into task_state_inst_microsar and task_state_inst_autocore.
  • Internally translate task_state_instrumentation into task_state_inst_microsar.
  • Add new command line flag --task_state_instrumentation_autocore.
  • Implement Elektrobit AutoCore instrumentation use case.
• 12-Jun-2023
  • Add spinlock_trace_variable_definition attribute for spinlock instrumentation use case.
  • Rename spinlock_instrumentation.generate_instrumentation to spinlock_generate_instrumentation.
• 07-Jun-2023
  • Add trace_variable_definition attribute for task state and runnable instrumentation use cases.
  • This is useful to define vendor specific includes to map the trace variable.
• 16-May-2023
  • Add feature to print symbols that have to be traced for profiling based on the current Profiler XML file.
• 01-May-2023
  • Add software_based_coreid_gen attribute for task state instrumentation use case. If this attribute is true, the hook implementation uses the core ID from the hook macro. If it is false, the MASK_CORE macro is defined to 0 and the core ID from the hardware trace (if available) is used.
• 18-Apr-2023
  • Make template_directory attribute obsolete.
  • Introduce vector_os_timing_hooks_h and vector_os_timing_hooks_c to specify Vector OS instrumentation files.
• 11-Apr-2023
  • Exit with better error message for ORTI/EB Os_config.h mismatch.
  • Log iTCHi version date in global exception handler.
  • Update readme to document all configuration attributes.
  • Fix RH850 Software Trace Runnable templates.
• 14-Mar-2023
  • Add support for native complex task state analysis to GUI and document in readme.
• 20-Jan-2023
  • Implement Running Task and ISR support for KPIT KSAR OS.
• 18-Jan-2023
  • Fix issue where mismatch between running task objects and number of cores would cause an exception.
  • Catch exception globally and ask user to create a ticket if that happens.
• 10-Jan-2023
  • Implement support for complex task state analysis natively in winIDEA
• 12-Dec-2022
  • Do not write MaskCore for ARTI by default (meaning we take the Core ID from the trace)
  • Do not reference ORTI file for ARTI
  • Handle multiple states with the same name for ARTI
• 07-Oct-2022
  • Add preliminary ARTI support.
  • Improve error message if ORTI file cannot be parsed.
• 09-Aug-2022
  • Use the same RTE Runnable template file for all OSes.
  • Generate Core instead of SourceCore because the latter is obsolete.
• 18-Jul-2022
  • Update Vector RTE Runnable template to better facilitate different multi-core architectures.
• 21-Jun-2022
  • Significantly update readme.
• 16-Jun-2022
  • Add STM trace support for instrumented Runnable profiling.
  • Update Vector Runnable template to include trace type.
  • Trace types are the same as for Thread profiling.
  • Update documentation for all config attributes.
• 24-Apr-2022
  • Rename btf_export_mapping_prefix to inspector_group_btf_states_prefix.
• 20-Apr-2022
  • Finalize spinlock support by adding spinlock_instrumentation attribute.
  • This feature is not part of the official winIDEA release as of today.
• 06-Apr-2022
  • Add a configuration option create_preemption_aware_running_states for the task state Inspectors use case.
  • If this flag is true, iTCHi creates an additional Inspector for each task, that has a running state RUNNING_ that correctly handles preemptions.
  • Set this attribute to true for more accurate gross execution time metrics.
• 21-Mar-2022
  • Add STM trace support for instrumented task state profiling.
  • Update Os_TimingHooks template generation to account for trace type.
  • Trace types are currently data_trace, stm_trace, and software_trace.
• 15-Feb-2022
  • Add ‘btf_export_mapping_prefix’ to add a prefix to the BTF states for the Inspectors use case. This is helpful when using Inspector groups.
• 11-Feb-2022
  • Fix bug that READY_ISR is not considered for BTF export.
• 10-Feb-2022
  • Deprecate autosar_to_physical_core and winidea_trd_file attributes.
  • Introduce orti_core_to_soc_core attribute.
  • Introduce orti_core_to_core_name attribute.
  • Introduce task_core_to_core_name attribute.
  • Utilize the new attributes to support Inspectors on SoCs like Traveo-II and Chorus10M
  • Improve logging and error handling.
• 03-Feb-2022
  • Task State Complex expression correctly uses running Task/ISR mode.
  • Task State Complex expression generates ISR Inspectors.
• 01-Feb-2022
  • Do not write empty Types as that violates the Profiler XML schema.
• 21-Dec-2021
  • Create MDF4 export configuration for MICROSAR instrumentation use case.
• 17-Dec-2021
  • Update MICROSAR instrumentation template to differentiate between RUNNING task and ISR states.
  • The MICROSAR instrumentation must be updated by the user to avoid errors.