Creation of a core dump via runtime function

	Available from TC3.1.4026.14 To use the CreateCallStackCoreDump() function, version 4026.14 is required on both the engineering and runtime side.

	Core dump can only be used with the associated compile info file If you archive or save a core dump file, please note that the associated project and associated compile info file (.compileinfo file, which is stored, for example when creating the project, in the "_CompileInfo" folder) must be present in order to load a core dump. If this is not the case, TwinCAT cannot use the dump later. Please also note here the setting options on the Settings tab. With the help of the Core Dump* setting, you can configure whether the core dump file, which may be located in the project directory, is to be saved together with the available compile info files in a TwinCAT file archive.

The CreateCallStackCoreDump() function is available to create a core dump at runtime. You can use this function to generate a core dump from the control code, which contains the call stack for the line of code calling the function. A part of the core dump designation can be transferred as a parameter. Further information on naming can be found later in this chapter.

Storage path

By default, the core dump is stored in the boot folder of the target system. Further information on the (adjustable) storage path can be found below: Storage path for automatic creation.

CreateCallStackCoreDump() function

Inputs

VAR_INPUT
    sName : STRING[40];
END_VAR

Name	Type	Description
sName	STRING[40]

Performance notes

	Please observe the following performance notes on the CreateCallStackCoreDump() function.

To enable the dump file to be generated during runtime, only the information about the call stack is saved. Variable values are not included in the dump.
Note that the reading of the call stack takes place in the real-time context and therefore real-time performance is used.
The core dump file is written asynchronously by the AuxTask when it is in the Idle state.

Name of the core dump file

The name of the core dump file generated by CreateCallStackCoreDump() is:

Port_<port of the PLC project>_CallStackDump_<value of the transferred input variable sName>.<Call Stack Checksum>.core

Sample:

The following function call within a PLC project with port 851, for example, generates a core dump with the following name.

CreateCallStackCoreDump('CheckBounds_IdxTooLow');

Port_851_CallStackDump_CheckBounds_IdxTooLow.2322085807.core

The checksum in the name is formed via the call stack so that only one dump is stored per call stack. If the same call stack were to produce another dump in a different cycle, it would have the same name and overwrite the previous file.

Limiting the number of core dump files

To limit memory consumption, the maximum number of core dump files is limited to 10. This means that a maximum of 10 core dump files are stored, which are created using the runtime function. If 10 files already exist and another dump is to be created, a previous dump file is overwritten.

Loading a core dump created by runtime function from the target system into the project

You can load the core dump from the target system into the project directory in online mode. In addition, you can load a core dump from the project directory into the project in offline mode. You will then receive an online view of the PLC project with the call stack at the time the core dump file was created.

Prerequisites:

In the development environment, you have opened the project that created the core dump file on the target system. The PLC project is in online mode in the development environment.

The "_CompileInfo" folder of the project contains a compile info file matching the core dump.

1. Use Command Generate core dump to load the core dump from the target system.

TwinCAT copies the core dump file with the name <PLC_project_name>.<PLC_project_GUID>.core into the local PLC project directory.

2. Log the PLC project out.

3. Use the Command Load core dump to load the desired core dump into the project.

TwinCAT displays an online view of the PLC project. You will see the call stack at the time the core dump was created. Information: A core dump that is created using the runtime function CreateCallStackCoreDump() does not contain any variable values for performance reasons.

4. After completing the core dump analysis, select the Command Close core dump.

TwinCAT closes the core dump view of the PLC project. The development environment reappears with the views of normal offline operation.

	Core dump online view: not all commands available In the online view that TwinCAT generates when loading the core dump into the project, menu commands appear as available that are not effective in this state. If you select such a command, you will receive a corresponding message. In addition, you can only close the core dump view using the command Close core dump. The Logout command is not effective in this view.

Sample: Generation of a core dump at runtime in CheckBounds()

The following is a sample in which the CreateCallStackCoreDump() function is called in the Bound Checks (POU CheckBounds) function for implicit checks.

This allows you to find out in which line of code a possible access outside the valid array limits occurs without stopping the runtime using a breakpoint.

By calling CreateCallStackCoreDump() within the corresponding IF branches of CheckBounds(), the call stack with the position of the faulty array access is saved in a core dump during runtime and can be loaded at a suitable time for analysis purposes.

Function CheckBounds:

// Implicitly generated code : DO NOT EDIT
FUNCTION CheckBounds : DINT
VAR_INPUT
    index, lower, upper: DINT;
END_VAR

// Implicitly generated code: Only an implementation suggestion
{noflow}
IF index < lower THEN
    CreateCallStackCoreDump('CheckBounds_IdxTooLow');
    CheckBounds := lower;
ELSIF index > upper THEN
    CreateCallStackCoreDump('CheckBounds_ IdxTooHigh');
    CheckBounds := upper;
ELSE 
    CheckBounds := index;
END_IF

For example, a core dump with the following name is created:

Port_851_CallStackDump_CheckBounds_IdxTooLow.2322085807.core

See also:

Using function blocks for implicit checks