iTCHi Readme

Introduction

iSYSTEM trace configuration helper iTCHi (iTCHi) 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 system1 or request a training session from an iSYSTEM 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 iSYSTEM Profiler XML file, a Profiler Inspectors JSON file2, 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 file3 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 help4. 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 Instrumentation

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

This command extracts the thread identifiers from the ORTI file and writes them to the Profiler XML file. It also creates a Thread object, as well as TypeEnums for BTF export and for the task state mapping. To use this command add the task_state_instrumentation object to your configuration file.

{
    "task_state_instrumentation": {
        "task_mapping_file": "",
        "template_directory": "",
        "instrumentation_type": "data_trace",
        "trace_variable": "isystem_trace",
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "db_push_register": "0x0"
    }
}

The attribute task_mapping_file is currently not used. You can remove it or leave it as it is.

If the attribute template_directory points to a directory iTCHi writes a template Vector Timing-Hooks instrumentation C and H file into that directory. You can then include these files into the build process of your MICROSAR application.

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.

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 Python5. 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 iSYSTEM 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, first specify the signals in the iTCHi configuration file.

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

Spinlock Instrumentation

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

Please contact your iSYSTEM 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 Software Trace (but not data trace) this use-case may be possible with additional (manual) configuration. Contact an iSYSTEM FAE in that case. Task/ISR tracing is not supported with program-flow trace.

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_expression. 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] [--running_taskisr]
                [--running_taskisr_btf] [--running_taskisr_sampling]
                [--task_state_single_variable] [--task_state_complex_expression]
                [--task_state_instrumentation] [--runnable_instrumentation]
                [--running_taskisr_ossignaling] [--runnable_program_flow]
                [--version]

iSYSTEM Trace Configuration Helper iTCHi (iTCHi)

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.
  --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.
  --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_instrumentation
                        Prepares profiler XML for task state tracing based on a single global variable.
  --runnable_instrumentation
                        Prepares profiler XML for instrumentedRunnable tracing and creates instrumentation.
  --running_taskisr_ossignaling
                        Not implemented: See readme.
  --runnable_program_flow
                        Prepares profiler XML for Runnable tracing based on program flow trace.
  --signals             Prepares profiler XML for signals.
  --spinlock_instrumentation
                        Not yet released: prepares profiler XML for spinlock profiling.

  --version             Prints build date and exits.

Config attributes

attribute description
orti_file Mandatory path to the OS ORTI file.
profiler_xml_file Mandatory path to the Profiler XML file that iTCHi will generate.
running_taskisr default_task Name of default task; only required if ORTI file does not include NO_TASK or INVALID_TASK.
running_taskisr default_isr2 Name of default ISR; only required if ORTI file does not include NO_ISR or INVALID_ISR.
running_taskisr search_replace_list Rename Task or ISR variable to a static symbol if it includes a pointer. iTCHi will consecutively replace the first string with the second.
running_taskisr orti_core_to_soc_core Map an AUTOSAR OS core to a different physical core. For example, to remap AUTOSAR core 0 to SoC core 3, enter “0” and “3”.
running_taskisr orti_core_to_core_name Rename an AUTOSAR OS core. For example, to rename AUTOSAR core 0 to ‘Cortex-M4.1’, enter “0” and “Cortex-M4-1”.
task_state task_to_core_mapping Explicitly map tasks to AUTOSAR cores if ‘task_to_core_heuristic’ does not work.
task_state task_to_core_heuristic If ‘true’, iTCHi tries to extract the core ID for each task from the ORTI STATE attribute.
task_state autocore_os_config_h For Elektrobit AutoCore OS, point this attribute to the ‘OsConfig.h’ file.
task_state autocore_mk_gen_config_h For Elektrobit SafetyOS, point this attribute to the ‘MkGenConfig.h’ file.
task_state_inspectors inspector_group_btf_states_prefix iTCHi prefixes the BTF TypeEnums with this string. This is helpful when using Inspector groups.
task_state_inspectors constant_variables Use this attribute to map specific symbols (variables) to a specific value for task state based profiling. This is helpful when a variable only changes once during startup.
task_state_inspectors create_data_areas If ‘true’, iTCHi adds the required data areas for the Task Inspectors to the Profiler XML.
task_state_inspectors create_preemption_aware_running_state If ‘true’, iTCHi adds a second Inspector for each task that provides a second ‘RUNNING_’ state with correct preempt statistics.
task_state_inspectors default_state Default state for Inspectors; usually it is SUSPENDED or UNKNOWN.
task_state_inspectors inspectors_file iTCHi generates the Inspectors into this file. It should have a ‘.json’ file ending.
task_state_inspectors parent_area_template References the parent object for the Inspectors. The default should be fine.
task_state_inspectors reference_inspectors_file_from_xml If ‘true’, the Profiler XML references the Inspectors file and winIDEA loads them automatically. To import the Inspectors manually, use ‘false’.
task_state_inspectors task_core_to_core_name Map a SoC Task core ID to a different core name. If a Task on core 0 should reference CPU2, enter “0” and “CPU2”
task_state_instrumentation task_mapping_file Obsolete.
task_state_instrumentation template_directory Path to a directory into which iTCHi will generate a template for the Thread instrumentation. You can then adapt the header and source files and add them to your build.
task_state_instrumentation instrumentation_type Select the trace type. It can be ‘data_trace’, ‘stm_trace’, or ‘software_trace’. Default is ‘data_trace’.
task_state_instrumentation trace_variable If ‘instrumentation_type’ is ‘data_trace’, this specifies the name of the Thread instrumentation trace variable.
task_state_instrumentation stm_base_address If ‘instrumentation_type’ is ‘stm_trace’, this specifies the STM base address.
task_state_instrumentation stm_channel If ‘instrumentation_type’ is ‘stm_trace’, this specifies the STM Thread channel.
task_state_instrumentation db_push_register If ‘instrumentation_type’ is “software_trace” this specifies the Thread DB Push register.
runnable_instrumentation isystem_vfb_hooks_c Path to the VFB hook implementation file that iTCHi generates.
runnable_instrumentation rte_hook_h If you use Vector MICROSAR OS, point this attribute to the ‘RteHook.h’ file.
runnable_instrumentation rte_xdm If you use Elektrobit AutoCore OS, point this attribute to the ‘RTE.xdm’ file.
runnable_instrumentation regex A regular expression to extract hooks from ‘RteHook.h’. Adapt this to find other hooks, but preserve the three Python regex matching groups.
runnable_instrumentation trace_variable If Runnable ‘instrumentation_type’ is ‘data_trace’, this specifies the name of the Runnable trace variable.
runnable_instrumentation template_file If specified, iTCHi writes the VFB trace template into it. The user can then adapt it, and iTCHi will use it in the following runs.
runnable_instrumentation instrumentation_type Select the Runnable trace type. It can be ‘data_trace’, ‘stm_trace’, or ‘software_trace’. Default is ‘data_trace’.
runnable_instrumentation stm_base_address If ‘instrumentation_type’ is ‘stm_trace’, this specifies the STM base address.
runnable_instrumentation stm_channel If ‘instrumentation_type’ is ‘stm_trace’, this specifies the STM Runnable channel.
runnable_instrumentation db_push_register If ‘instrumentation_type’ is “software_trace” this specifies the Runnable DB Push register.
runnable_program_flow runnables List of functions that should be treated as Runnables. Adding regular functions as Runnables will likely lead to undesired behavior.
signals List of signals (variables) that should be visualized as separate objects in the Profiler timeline. These signals are also exported to BTF.
spinlock_instrumentation generate_instrumentation Set this to true to generate spinlock instrumentation. Only works in combination with thread instrumentation and “template_directory”.
spinlock_instrumentation spinlock_trace_variable Name of of the spinlock trace variable. Defaults to “isystem_trace_spinlock”.

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_instrumentation": {
        "task_mapping_file": "",
        "template_directory": "",
        "instrumentation_type": "data_trace",
        "trace_variable": "isystem_trace",
        "stm_base_address": "0x0",
        "stm_channel": "0x0",
        "db_push_register": "0x0"
    },
    "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"
    },
    "runnable_program_flow": {
        "runnables": []
    },
    "signals": [],
    "spinlock_instrumentation": {
        "generate_instrumentation": false,
        "spinlock_trace_variable": "isystem_trace_spinlock"
    },
    "commands": {
        "running_taskisr": false,
        "running_taskisr_btf": false,
        "running_taskisr_sampling": false,
        "task_state_single_variable": false,
        "task_state_complex_expression": false,
        "task_state_instrumentation": false,
        "runnable_instrumentation": false,
        "runnable_program_flow": false,
        "signals": false,
        "spinlock_instrumentation": false
    }
}

Changelog


  1. iSYSTEM Application Notes↩︎

  2. iSYSTEM Profiler Inspectors↩︎

  3. OSEK Run-Time Interface↩︎

  4. winIDEA Online Help↩︎

  5. Python Regex Grouping↩︎