1.3.5. IEC Task Management¶

The IEC task management is done in the component CmpIecTask.

Four different types of tasks are possible:

Cyclic tasks: These tasks are executed in a specified interval.
Event tasks: These tasks are executed once every time, if a specified IEC BOOL variable changed its value from FALSE to TRUE.
Freewheeling tasks: These tasks are executed without a specified cycle in a loop. To enable running tasks with a lower priority, the freewheeling task frees the processor in a specified way:

Default: 20% of its execution time, the task will sleep at the end of a cycle
If a processor load maximum is specified in the scheduler, this is the load value for the freewheeling tasks too, e.g.

processor load maximum = 60%

execution time of the freewheeling task = 10ms

-> Sleep time = (100% - processor load maximum) * 10ms = 40% * 10ms = 4ms
Fix sleep time:

A fix sleep time can be specified for the freewheeling task.

This value can be specified additionally in the scheduler with the following setting:

[CmpSchedule]

Task.Freewheeling.Cycletime=10

In this example, every freewheeling task sleeps at the end of its cycle 10ms.

External Event tasks: An external event task is executed every time, an external (runtime event, hardware event) occurred. The event is specified by name in the device description of the device. This event can be specified in the task configuration in CODESYS, if external event task is selected.

The list of all IEC-tasks in an application is generated by CODESYS in the form of initialized IEC data structures. At download, this list is created during initialization and is transmitted to the CmpIecTask component after initialization. The tasks are reported then to the scheduler and are created specifically, in accordance with their type, as operating system tasks.

The format of the task description is explained in more detail below.

1.3.5.1. Data Format of the task description¶

The download message contains information about an application’s tasks in the form of initialized IEC data structures.

The IEC data structures are initialized with the other variables after the download.

The data structures are defined as follows:

#define Cyclic 0x0000
#define Event 0x0001
#define External 0x0002
#define Freewheeling 0x0003
typedef struct
{
  char stName[51];
  short nPriority;
  short KindOfTask;
  char bMicroseconds;
  unsigned int dwInterval;
  unsigned int dwEventFunctionPointer;
  char stExternalEvent[51];
  unsigned int dwTaskEntryFunctionPointer;
  int tLastCycleTime;
  int tAverageCycleTime;
  int tMaxCycleTime;
  int tMinCycleTime;
  int tJitterMax;
  int tJitterLast;
}Task\_Info;

typedef struct
{
  short nTasks;
  char stApplicationName[51];
  Task_Info* ptaskinfo;
}sys_setup_tasks_struct;

The sys_setup_tasks_struct structure contains the entire task configuration of an application.

1.3.5.2. Creating IEC tasks¶

void CDECL __sys__setup__tasks(sys_setup_tasks_struct* p)

This function is called after a download or after the boot project has been loaded. A pointer to a variable in the sys_setup_tasks_struct structure is passed. This function saves a pointer to each task and adds this task to the scheduler component.

1.3.5.3. Creating an external event task¶

As an external event we describe an event in the runtime system, on which a task can be activated. This event is typically generated out of a runtime system component, but could also be generated out of the IEC-Code. An external event is always identified by its name, so the name of the event must be known.

To realize an external event task, the following issues must be implemented:

You need a description of this external event in your device description. For this the following settings are needed (see Task configuration):

(1) /DeviceDescription/Device/ExtendedSettings/ts:TargetSettings/ts:section[@name=’taskconfiguration’]/ts:setting[@name=’supportexternal’]/ts:value=1

(2) /DeviceDescription/Device/ExtendedSettings/ts:TargetSettings/ts:section[@name=’taskconfiguration’]/ts:setting[@name=’externalevents’]/ts:value=<externalevents> <externalevent> <name>myCyclicInterrupt</name> </externalevent></externalevents>

Example of an external event named “myCyclicInterrupt”:
```
<ts:section name="taskconfiguration">
   <ts:setting name="externalevents" type="cdata" access="hide">
      <ts:value><![CDATA[
         <externalevents>
             <externalevent>
                 <name>myCyclicInterrupt</name>
             </externalevent>
         </externalevents>
     ]]></ts:value>
   </ts:setting>
</ts:section>
```
The runtime system must be able to recognizes and store the event, that was assigned to the specified task. There are two ways:

Option 1: All schedulers of CODESYS Control are now supporting a new interface to easily implement “external events” which can be used for “external event tasks”.

The interface functions might be used like this:
HookFunction(): case CH\_INIT3: { s\_hExtEventTask = SchedRegisterExternalEvent("myCyclicInterrupt", NULL); ... case CH\_EXIT3: { SchedUnregisterExternalEvent(s\_hExtEventTask); ... myCyclicInterruptHandler(): SchedPostExternalEvent(s\_hExtEventTask); ...
Option 2:

In the runtime system, the CmpSchedule component offers two events called EVT_ExternalEventTaskCreateDone and EVT_PrepareExternalEventTaskDelete for the case that an external event task is created or deleted. So first you have to register to these events (how to handle an external event is implemented as an example in the CmpTemplate.c module of the Runtime Toolkit).

In your callback routine of the EVT_ExternalEventTaskCreateDone event you have to store the hEvent parameter. And in the callback routine of the EVT_PrepareExternalEventTaskDelete event, you have to remove the hEvent.

Last but not least you have to send this event always when the corresponding external event has occurred in the runtime system (like an interrupt, etc.). To activate the task once, that is assigned to this external event task, you have to send this event by CAL_SysEventSet(hEvent).

After this, you can assign the external event specified in the device description to your task in your IEC program. After downloading your application this task should be executed every time the event is sent in the runtime system.

Equivalent to the handling in the runtime system, you can handle an external event in IEC-Code. All needed runtime system interfaces for that are available as external System-Libraries.

Note

Debugging inside of external events is only supported for

CmpSchedule. All other scheduler variants are ignoring breakpoints within external events.

1.3.5.4. Jitter of IEC Tasks¶

Definition of Terms¶

Latency is the delay between the invocation of a task and the actual start of its execution (release).

The release jitter is quantified by the difference between the maximum and minimum latency for all task calls.

J_r is defined as L_max – L_min.

In the case that L_max = L_min, the release jitter J_r of 0 results. This would correspond to a plain offset shift.

Periodic jitter: J_per = T_per - T0

In this case, T_per is the period duration of the task and T0 is the ideal period duration.

Period jitter is the deviation of the cycle time of a task from the ideal period over a number of randomly selected cycles. When we are given a number of individual task periods, we can measure each one and calculate the average task period as well as the standard deviation and peak-to-peak value.

Positive and negative values can occur in the case of the periodic jitter J_per. To prevent drift, the sum of all negative J_per values and the sum of all positive J_per values have to balance each other.

Jitter based on the deviation of the actual from the scheduled task start time

J_err_t = t_r – t_r_planned

In this case, t_r is the task release time and t_r_planned is the planned task start time.

The planned task start time t_r_planned corresponds to the time of invocation plus the expected ideal (jitter-free) latency.

J_err_t is the deviation of the task start time from the scheduled task start time.

Positive and negative values can occur in the case of J_err_t.

Jitter based on the deviation of the current task start time from the target task start time based on the task start time with the maximum negative periodic jitter

As soon as a negative periodic jitter occurs, its task start time is used as the basis (= reference value) for all future target task start times. Until a negative periodic jitter occurs again, its task start time replaces the previous reference value. (As long as no negative periodic jitter has occurred, the first task start time is the reference value.)

J_t_r_min = t_r - (t_r_min + n ⋅ T0)

In this case, t_r is the current release time of the task, t_r_min is the task start time with the maximum negative periodic jitter, n ⋅ T0 is a multiple of the ideal period duration, and n is the number of cycles that have elapsed since setting the reference value t_r_min.

J_t_r_min is the deviation of the actual task start time from the target task start time based on the task start time with the maximum negative periodic jitter.

For J_t_r_min, negative values are the exception.

Diagnostics¶

IEC Task Jitter System Trace¶

If the SysCpuMultiCore and CmpTraceMgr components are integrated in the runtime system, there will be created a system trace (= device trace), which can be upload in CODESYS to see the IEC task jitter as a trace.

To enable this, you have to add the following setting into your runtime configuration file (.cfg file):

[CmpIecTask]
EnableTaskTrace=1

To see the trace, you have to add a trace object under your device in CODESYS and with the command “upload” you can upload and start the trace with the name “IecTaskJitter.<AppName>.<TaskName>”.